code-foundry 0.32.4 → 0.34.0

package/src/commands/release.mjs

@@ -1,6 +1,7 @@
 // @ts-check
 
-import { existsSync, readFileSync } from 'node:fs'
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { approvedReleaseFiles, buildReleaseRecoveryPlan, classifyReconciliation, readReleaseConfig, selectGeneratedReleasePrs, validateReleasePullRequests } from '../lib/release-policy.mjs'
@@ -9,10 +10,11 @@ import { hasDeliveredHook, releaseDeliveryKey, selectHookDelivery } from '../lib
 /** @typedef {{ target: string, dryRun: boolean, github: boolean, base: string, head: string }} ReleaseOptions */
 
 /**
- * Reconcile staging after Release Please updates main. The local mode is
- * deterministic and suitable for CI; --github mirrors staging onto main's
- * tip through the GitHub API (fast-forward, then forced, then a linear sync
- * commit) and otherwise fails closed.
+ * Reconcile staging after Release Please updates main.
+ *
+ * Local mode is deterministic and suitable for CI; --github uses strict
+ * lease-based mirror retries with fresh refetch/reclassification and fails
+ * closed if classification or remote mutation fails.
  * @param {string} root
  * @param {ReleaseOptions} options
  */
@@ -20,51 +22,264 @@ export function reconcileRelease(root, options) {
   const target = resolve(root)
   const base = options.base || 'main'
   const head = options.head || 'staging'
-  const mainSha = git(target, ['rev-parse', `origin/${base}`]) || git(target, ['rev-parse', base])
-  const stagingSha = git(target, ['rev-parse', `origin/${head}`]) || git(target, ['rev-parse', head])
-  const mergeBaseSha = git(target, ['merge-base', mainSha, stagingSha])
-  // Compare the branch tips directly. Release Please may rebase or recreate
-  // commits during promotion, leaving equivalent code with different ancestry.
-  // Comparing both tips preserves the fail-closed behavior for real content
-  // differences without mistaking that normal history rewrite for a change.
-  const mainChangedPaths = diffNames(target, stagingSha, mainSha)
-  const stagingChangedPaths = diffNames(target, mainSha, stagingSha)
-  const plan = classifyReconciliation({
-    mainSha,
-    stagingSha,
-    mergeBaseSha,
-    mainChangedPaths,
-    stagingChangedPaths,
-    allowed: approvedReleaseFiles(readReleaseConfig(target)),
-  })
-  console.log(JSON.stringify({ base, head, ...plan }, null, 2))
-  if (plan.action === 'fail') throw new Error(plan.reason + (plan.unexpected?.length ? ` Unexpected paths: ${plan.unexpected.join(', ')}` : ''))
-  if (!['fast-forward', 'pull-request', 'aligned'].includes(plan.action) || !options.github || options.dryRun) return plan
-  if (!plan.targetSha) return plan
+  const allowed = approvedReleaseFiles(readReleaseConfig(target))
+  let state = resolveReconciliationState(target, base, head, allowed, options.github)
+  if (state.plan.action === 'fail') {
+    throw new Error(formatReconciliationFailure(state.plan))
+  }
+  console.log(JSON.stringify({ base, head, ...state.plan }, null, 2))
+  if (!['fast-forward', 'rebase-staging', 'aligned'].includes(state.plan.action) || !options.github || options.dryRun) return state.plan
+  if (state.plan.action === 'aligned' && state.mainSha === state.stagingSha) return state.plan
   if (!process.env.GITHUB_REPOSITORY) throw new Error('GITHUB_REPOSITORY is required for --github reconciliation.')
   const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN
   if (!token) throw new Error('GH_TOKEN or GITHUB_TOKEN is required for --github reconciliation.')
-  const targetSha = /** @type {string} */ (plan.targetSha)
-  // 1. Verified fast-forward through the API (linear, no force).
-  const fastForward = spawnSync('gh', [
-    'api', '--method', 'PATCH', `repos/${process.env.GITHUB_REPOSITORY}/git/refs/heads/${head}`,
-    '-f', `sha=${targetSha}`, '-F', 'force=false',
-  ], { cwd: target, stdio: 'inherit', env: { ...process.env, GH_TOKEN: token } })
-  if (fastForward.status === 0) return { ...plan, synchronization: 'fast-forward' }
-  // 2. Forced update when staging may be rewritten without violating the
-  // linear-history rule (main's tip is linear and already contains staging's
-  // content, so nothing unpromoted is lost).
-  const forced = spawnSync('gh', [
-    'api', '--method', 'PATCH', `repos/${process.env.GITHUB_REPOSITORY}/git/refs/heads/${head}`,
-    '-f', `sha=${targetSha}`, '-F', 'force=true',
-  ], { cwd: target, stdio: 'inherit', env: { ...process.env, GH_TOKEN: token } })
-  if (forced.status === 0) return { ...plan, synchronization: 'forced' }
-  // 3. Linear sync commit fallback: staging keeps its history and receives
-  // main's tree as a single-parent commit, which the ruleset always accepts.
-  const syncSha = createLinearSyncCommit(target, stagingSha, targetSha)
-  const push = spawnSync('git', ['push', 'origin', `${syncSha}:refs/heads/${head}`], { cwd: target, stdio: 'inherit', env: { ...process.env, GH_TOKEN: token } })
-  if (push.status !== 0) throw new Error(`GitHub refused the linear synchronization of ${head}.`)
-  return { ...plan, syncSha, synchronization: 'linear-commit' }
+  const maxAttempts = 3
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    state = resolveReconciliationState(target, base, head, allowed, true)
+    if (state.plan.action === 'fail') throw new Error(formatReconciliationFailure(state.plan))
+    if (state.plan.action === 'aligned' && state.mainSha === state.stagingSha) return state.plan
+    const mutation = executeReconciliationMutation(target, head, state)
+    if (mutation.success) return { ...state.plan, ...mutation.result }
+    if (!mutation.retry) throw new Error(mutation.error)
+    const remoteSha = remoteRefSha(target, head)
+    if (remoteSha === state.stagingSha) {
+      throw new Error(`${head} synchronization was rejected by an exact lease while remote ${head} tip remained ${state.stagingSha}. ` +
+        'Update branch protection or remote policy to permit this mutation, then retry. ' +
+        `Last failure detail: ${mutation.error}`)
+    }
+  }
+  throw new Error(`Reconciliation of ${head} was retried but failed while the branch moved concurrently.`)
+}
+
+/**
+ * Resolve current reconciliation state and plan from current refs.
+ * @param {string} target
+ * @param {string} base
+ * @param {string} head
+ * @param {Set<string>} allowed
+ * @param {boolean} requireRemote
+ */
+function resolveReconciliationState(target, base, head, allowed, requireRemote) {
+  validateRefName(base)
+  validateRefName(head)
+  if (requireRemote) refreshRemoteRefs(target, base, head)
+  const mainSha = resolveRef(target, base, requireRemote)
+  const stagingSha = resolveRef(target, head, requireRemote)
+  if (!mainSha || !stagingSha) {
+    return {
+      plan: {
+        action: 'fail',
+        reason: `Missing ${!mainSha ? `main (${base})` : `staging (${head})`} or staged branch ref during reconciliation.`,
+      },
+      mainSha,
+      stagingSha,
+      mainOnlyCommits: [],
+      stagingOnlyCommits: [],
+    }
+  }
+  try {
+    const mainOnlyCommits = divergentCommits(target, stagingSha, mainSha)
+    const stagingOnlyCommits = divergentCommits(target, mainSha, stagingSha)
+    const plan = classifyReconciliation({
+      mainSha,
+      stagingSha,
+      mainOnlyCommits,
+      stagingOnlyCommits,
+      allowed,
+    })
+    return { plan, mainSha, stagingSha, mainOnlyCommits, stagingOnlyCommits }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      plan: {
+        action: 'fail',
+        reason: `Failed to inspect divergent commits: ${message}`,
+      },
+      mainSha,
+      stagingSha,
+      mainOnlyCommits: [],
+      stagingOnlyCommits: [],
+    }
+  }
+}
+
+/** @param {{ reason: string, unexpected?: string[] }} plan */
+function formatReconciliationFailure(plan) {
+  return `${plan.reason}${plan.unexpected?.length ? ` Unexpected paths: ${plan.unexpected.join(', ')}` : ''}`
+}
+
+/** @param {string} ref */
+function validateRefName(ref) {
+  const result = spawnSync('git', ['check-ref-format', '--branch', ref], { encoding: 'utf8' })
+  if (result.status !== 0) throw new Error(`Invalid branch reference: ${ref}`)
+}
+
+/** @param {string} target @param {string} ref @param {boolean} requireRemote @returns {string} */
+function resolveRef(target, ref, requireRemote) {
+  const remote = git(target, ['rev-parse', `origin/${ref}`])
+  if (remote) return remote
+  if (!requireRemote) return git(target, ['rev-parse', ref])
+  return ''
+}
+
+/** @param {string} target @param {string} base @param {string} head */
+function refreshRemoteRefs(target, base, head) {
+  const result = spawnSync('git', ['fetch', 'origin', base, head], { cwd: target, encoding: 'utf8' })
+  if (result.status !== 0) throw new Error(`Failed to refresh origin/${base} and origin/${head} before reconciliation.`)
+}
+
+/** @param {string} target @param {string} branch */
+function remoteRefSha(target, branch) {
+  const result = spawnSync('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], { cwd: target, encoding: 'utf8' })
+  if (result.status !== 0) return ''
+  const [sha] = result.stdout.trim().split(/\t/, 1)
+  return sha || ''
+}
+
+/**
+ * Reconcile a single attempt from fresh state.
+ * @param {string} target
+ * @param {string} head
+ * @param {{
+ *  plan: ReturnType<typeof classifyReconciliation>,
+ *  mainSha: string,
+ *  stagingSha: string,
+ *  mainOnlyCommits: Array<{ sha: string, changedPaths: string[] }>,
+ *  stagingOnlyCommits: Array<{ sha: string, changedPaths: string[] }>,
+ * }} state
+ */
+function executeReconciliationMutation(target, head, state) {
+  if (!state.plan.targetSha) return { success: false, retry: false, error: `No target SHA for ${head} reconciliation.` }
+  if (state.plan.action === 'rebase-staging') {
+    let replaySha
+    try {
+      replaySha = replayOntoMain(target, state.mainSha, state.stagingOnlyCommits)
+    } catch (error) {
+      return {
+        success: false,
+        retry: false,
+        error: `Replay conflict while applying staging-only commits before replay: ${String(error instanceof Error ? error.message : error)}`,
+      }
+    }
+
+    const push = pushWithLease(target, head, state.stagingSha, replaySha)
+    if (push.status === 0) return { success: true, result: { synchronization: 'replay', replaySha } }
+    const classification = classifyPushFailure(head, push.message)
+    if (classification.category === 'authentication') {
+      return {
+        success: false,
+        retry: false,
+        error: `${head} authentication failed during replay push: ${classification.message}`,
+      }
+    }
+    if (classification.category === 'policy') {
+      return {
+        success: false,
+        retry: false,
+        error: `${head} reconciliation was blocked by branch policy: ${classification.message}`,
+      }
+    }
+    return { success: false, retry: true, error: `${head} synchronization failed with lease: ${classification.message}` }
+  }
+  const targetSha = /** @type {string} */ (state.plan.targetSha)
+  const leased = pushWithLease(target, head, state.stagingSha, targetSha)
+  if (leased.status === 0) return { success: true, result: { synchronization: state.plan.action === 'aligned' ? 'synced' : 'leased' } }
+  const classification = classifyPushFailure(head, leased.message)
+  if (classification.category === 'authentication') {
+    return {
+      success: false,
+      retry: false,
+      error: `${head} authentication failed during push: ${classification.message}`,
+    }
+  }
+  if (classification.category === 'policy') {
+    return {
+      success: false,
+      retry: false,
+      error: `${head} reconciliation was blocked by branch policy: ${classification.message}`,
+    }
+  }
+  return { success: false, retry: true, error: `${head} synchronization failed with lease: ${classification.message}` }
+}
+
+/** @param {string} target @param {string} head @param {string} expectedSha @param {string} tipSha */
+function pushWithLease(target, head, expectedSha, tipSha) {
+  const result = spawnSync('git', [
+    'push',
+    'origin',
+    `--force-with-lease=refs/heads/${head}:${expectedSha}`,
+    `${tipSha}:refs/heads/${head}`,
+  ], { cwd: target, encoding: 'utf8' })
+  const message = `${result.stdout?.trim() || ''}\n${result.stderr?.trim() || ''}`.trim() || `push with lease failed for ${head}.`
+  return {
+    status: result.status,
+    message: sanitizeReconcileOutput(message),
+  }
+}
+
+/**
+ * Classify a push failure to avoid leaking sensitive details and provide useful
+ * diagnostics while preserving exact-lease behavior.
+ * @param {string} branch
+ * @param {string} raw
+ */
+function classifyPushFailure(branch, raw) {
+  const message = sanitizeReconcileOutput(raw)
+  if (!message) return { category: 'other', message: `push with lease failed for ${branch}.` }
+  const lower = message.toLowerCase()
+  if (/permission denied|authentication failed|could not read from remote repository|publickey|not authorized|bad credentials/.test(lower)) {
+    return { category: 'authentication', message }
+  }
+  if (/remote:\s*error|protected branch|required status checks|pre-receive hook|branch policy|ruleset|gh006|gh007|gh008/.test(lower)) {
+    return { category: 'policy', message }
+  }
+  return { category: 'other', message }
+}
+
+/** @param {string} value */
+function sanitizeReconcileOutput(value) {
+  return value
+    .replace(/https?:\/\/[^\s@]+:[^\s@]*@/g, 'https://***:***@')
+    .replace(/https?:\/\/[^\s@]+@/g, 'https://***@')
+    .trim()
+}
+
+/**
+ * Replay staging-only commits onto a detached worktree at main.
+ * @param {string} target
+ * @param {string} mainSha
+ * @param {Array<{ sha: string, changedPaths: string[] }>} commits
+ */
+function replayOntoMain(target, mainSha, commits) {
+  const orderedCommits = commits.map((commit) => commit.sha).filter(Boolean)
+  if (!orderedCommits.length) return mainSha
+  const workspace = mkdtempSync(join(tmpdir(), 'code-foundry-reconcile-'))
+  const identityArgs = [
+    '-c',
+    'user.name=github-actions[bot]',
+    '-c',
+    'user.email=41898282+github-actions[bot]@users.noreply.github.com',
+  ]
+  try {
+    const added = spawnSync('git', ['worktree', 'add', '--detach', workspace, mainSha], { cwd: target, encoding: 'utf8' })
+    if (added.status !== 0) throw new Error(`Failed to create temporary replay worktree: ${added.stderr?.trim() || added.stdout?.trim()}`)
+    for (const sha of orderedCommits) {
+      const cherryPick = spawnSync('git', [...identityArgs, 'cherry-pick', sha], { cwd: workspace, encoding: 'utf8' })
+      if (cherryPick.status !== 0) {
+        spawnSync('git', ['cherry-pick', '--abort'], { cwd: workspace, encoding: 'utf8' })
+        const details = [cherryPick.stdout?.trim(), cherryPick.stderr?.trim()].filter(Boolean).join('\n')
+        throw new Error(`Cherry-pick of ${sha} failed while replaying staging commits: ${sanitizeReconcileOutput(details)}`)
+      }
+    }
+    const replayTip = git(workspace, ['rev-parse', 'HEAD'])
+    if (!replayTip) throw new Error('Failed to resolve replay tip SHA.')
+    const ancestry = spawnSync('git', ['merge-base', '--is-ancestor', mainSha, replayTip], { cwd: workspace, encoding: 'utf8' })
+    if (ancestry.status !== 0) throw new Error('Replayed head is not based on the current main tip.')
+    return replayTip
+  } finally {
+    spawnSync('git', ['worktree', 'remove', '--force', workspace], { cwd: target, encoding: 'utf8' })
+    rmSync(workspace, { recursive: true, force: true })
+  }
 }
 
 /**
@@ -148,29 +363,36 @@ function git(root, args) {
   return result.status === 0 ? result.stdout.trim() : ''
 }
 
-/**
- * Build a linear commit whose tree equals main's tip and whose parent is the
- * current staging tip. Staging requires linear history and main's tip almost
- * always sits behind promotion merge commits, so a direct fast-forward to
- * main's tip is rejected by the branch ruleset ("must not contain merge
- * commits"). A single-parent commit is always pushable and keeps staging
- * content-identical to main.
- * @param {string} root @param {string} parentSha @param {string} mainSha @returns {string}
- */
-function createLinearSyncCommit(root, parentSha, mainSha) {
-  const tree = git(root, ['rev-parse', `${mainSha}^{tree}`])
-  if (!tree) throw new Error('Failed to resolve the target tree.')
-  const identity = ['-c', 'user.name=github-actions[bot]', '-c', 'user.email=41898282+github-actions[bot]@users.noreply.github.com']
-  const result = spawnSync('git', [...identity, 'commit-tree', tree, '-p', parentSha, '-m', 'chore(release): synchronize staging with main'], { cwd: resolve(root), encoding: 'utf8' })
-  if (result.status !== 0) throw new Error(`Failed to create the synchronization commit: ${result.stderr.trim()}`)
-  return result.stdout.trim()
+/** @param {string} root @param {string} from @param {string} to @returns {Array<{ sha: string, changedPaths: string[] }>} */
+function divergentCommits(root, from, to) {
+  if (!from || !to || from === to) return []
+  const result = spawnSync('git', [
+    'log',
+    '--cherry-pick',
+    '--no-merges',
+    '--left-right',
+    '--reverse',
+    '--pretty=tformat:%m%H',
+    `${from}...${to}`,
+  ], { cwd: root, encoding: 'utf8' })
+  if (result.status !== 0) {
+    throw new Error(`Failed to enumerate divergent commits between ${from} and ${to}. ${result.stderr?.trim() || result.stdout?.trim()}`)
+  }
+  return result.stdout
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith('>'))
+    .map((line) => ({
+      sha: line.slice(1),
+      changedPaths: commitChangedPaths(root, line.slice(1)),
+    }))
+    .filter((entry) => entry.sha)
 }
 
-/** @param {string} root @param {string} from @param {string} to @returns {string[]} */
-function diffNames(root, from, to) {
-  if (!from || !to || from === to) return []
-  const result = spawnSync('git', ['diff', '--name-only', from, to], { cwd: root, encoding: 'utf8' })
-  return result.status === 0 ? result.stdout.split(/\r?\n/).filter(Boolean) : []
+/** @param {string} root @param {string} commitSha @returns {string[]} */
+function commitChangedPaths(root, commitSha) {
+  const result = spawnSync('git', ['diff-tree', '--no-commit-id', '--name-only', '-r', commitSha], { cwd: root, encoding: 'utf8' })
+  if (result.status !== 0) throw new Error(`Unable to read changed paths for commit ${commitSha}. ${result.stderr?.trim() || result.stdout?.trim()}`)
+  return result.stdout.split(/\r?\n/).filter(Boolean)
 }
 
 /** @param {string} root @param {string[]} args @returns {unknown} */

package/src/commands/sync.mjs

@@ -16,11 +16,18 @@ const standardFiles = [
   '.github/PULL_REQUEST_TEMPLATE.md', '.github/SECURITY.md', '.github/dependabot.yml',
   '.github/ISSUE_TEMPLATE/bug_report.yml', '.github/ISSUE_TEMPLATE/config.yml',
   '.github/ISSUE_TEMPLATE/feature_request.yml',
-  '.github/workflows/ci.yml', '.github/workflows/codeql.yml', '.github/workflows/draft-pr.yml',
+  '.github/workflows/validation.yml', '.github/workflows/draft-pr.yml',
   '.github/workflows/release-pr.yml', '.github/workflows/release.yml',
-  '.github/workflows/security.yml', '.github/workflows/test.yml', '.github/workflows/opencode-security.yml',
+  '.github/workflows/opencode-security.yml',
 ]
 
+/**
+ * Legacy event callers that the tiered validation caller replaces. Sync
+ * removes them only when they are recognized as Code Foundry-generated;
+ * custom workflows are always preserved byte-for-byte.
+ */
+const LEGACY_GENERATED_CALLERS = ['ci', 'test', 'security', 'codeql']
+
 const protectedFiles = new Set([
   'AGENTS.md', '.github/CODE_OF_CONDUCT.md', '.github/CONTRIBUTING.md',
   '.github/PULL_REQUEST_TEMPLATE.md', '.github/SECURITY.md', 'NOTICE',
@@ -72,6 +79,14 @@ export function syncRepository(options) {
   if (!['auto', 'native', 'mise'].includes(toolchain)) {
     throw new Error(`Unsupported toolchain: ${toolchain}; use auto, native, or mise.`)
   }
+  const mergeStrategy = configured(config.merge_strategy, 'rebase')
+  if (mergeStrategy !== 'rebase') {
+    throw new Error(`Unsupported merge_strategy: ${mergeStrategy}; the staging-release topology requires rebase for staging to main promotions.`)
+  }
+  const releaseMergeStrategy = configured(config.release_merge_strategy, '')
+  if (includesValue(features, 'release') && releaseMergeStrategy !== 'squash') {
+    throw new Error(`Unsupported release_merge_strategy: ${releaseMergeStrategy || '(unset)'}; release automation requires squash for Release Please version pull requests and never defaults to merge.`)
+  }
   const license = configured(config.license, existsSync(join(target, 'LICENSE')) ? 'preserve' : 'gpl-3.0-or-later')
   const changed = []
 
@@ -98,6 +113,10 @@ export function syncRepository(options) {
     }
     if ((file === 'LICENSE' || file === 'NOTICE') && license === 'preserve' && existsSync(destination)) continue
     if ((file === 'LICENSE' || file === 'NOTICE') && license === 'none') continue
+    // An explicit license policy makes the license block below the single
+    // owner of LICENSE; copying the runtime's own root LICENSE here would
+    // fight it and break idempotence on the next sync.
+    if (file === 'LICENSE' && license !== 'preserve' && license !== 'none') continue
     if (file === '.github/CODEOWNERS' && existsSync(destination)) continue
     let content = readFileSync(sourceFile)
     if (file === 'release-please-config.json') {
@@ -118,6 +137,18 @@ export function syncRepository(options) {
     }
   }
 
+  for (const stem of LEGACY_GENERATED_CALLERS) {
+    const destination = join(target, `.github/workflows/${stem}.yml`)
+    if (!existsSync(destination)) continue
+    if (isGeneratedEventCaller(readFileSync(destination, 'utf8'), stem, runtimeRepository)) {
+      changed.push(`.github/workflows/${stem}.yml`)
+      if (dryRun) console.log(`Would remove generated legacy caller ${stem}.yml; validation.yml replaces it.`)
+      else rmSync(destination, { force: true })
+    } else {
+      console.log(`Preserved ${stem}.yml: not recognized as a Code Foundry-generated caller.`)
+    }
+  }
+
   const releaseManifest = buildReleaseManifest(target, mergeReleaseConfig(target, sourcePath(source, 'release-please-config.json')))
   if (releaseManifest) {
     const manifestPath = join(target, '.release-please-manifest.json')
@@ -143,7 +174,11 @@ export function syncRepository(options) {
     const licenseFile = license === 'mit' ? 'MIT.txt' : license === 'agpl-3.0-or-later' ? 'AGPL-3.0-or-later.txt' : 'GPL-3.0-or-later.txt'
     const sourceLicense = join(source, '.github/licenses', licenseFile)
     if (!existsSync(sourceLicense)) throw new Error(`License template missing: ${sourceLicense}`)
-    writeOrReport(join(target, 'LICENSE'), readFileSync(sourceLicense), dryRun)
+    const licenseContent = readFileSync(sourceLicense)
+    if (!existsSync(join(target, 'LICENSE')) || !buffersEqual(licenseContent, readFileSync(join(target, 'LICENSE')))) {
+      changed.push('LICENSE')
+      writeOrReport(join(target, 'LICENSE'), licenseContent, dryRun)
+    }
     if (!existsSync(join(target, 'NOTICE'))) writeOrReport(join(target, 'NOTICE'), readFileSync(join(source, 'NOTICE')), dryRun)
   }
 
@@ -217,6 +252,11 @@ function shouldInclude(file, languages, features, config) {
   if (file === '.github/dependabot.yml') return includesValue(features, 'dependabot')
   if (file === '.github/workflows/opencode-security.yml') return ['true', 'auto'].includes(config.opencode_security ?? 'false')
   const workflow = file.match(/^\.github\/workflows\/([^/]+)\.yml$/)?.[1]
+  // The tiered validation caller supersedes the legacy ci/test/security/codeql
+  // event callers, so legacy feature names keep selecting it.
+  if (workflow === 'validation') {
+    return includesValue(features, 'validation') || LEGACY_GENERATED_CALLERS.some((legacy) => includesValue(features, legacy))
+  }
   return !workflow || includesValue(features, workflow)
 }
 
@@ -245,7 +285,13 @@ function renderWorkflow(content, config, repository, ref, rustCodeql) {
   const remotePrefix = `uses: ${repository}/.github/workflows/`
   let rendered = content.replaceAll(localPrefix, remotePrefix)
   rendered = rendered.replace(new RegExp(`${escapeRegExp(remotePrefix)}([^\\s@]+)`, 'g'), `$&@${ref}`)
-  rendered = rendered.replace(/^(\s+runtime-ref:)\s+.*$/m, `$1 ${ref}`)
+  // Pin every runtime reference in the rendered caller: the orchestrator input
+  // in the `with:` block and the mode job's runtime checkout. Self templates
+  // use ${{ github.sha }} and are only rewritten when rendered for consumers.
+  rendered = rendered.replace(/^(\s+runtime-ref:)\s+.*$/gm, `$1 ${ref}`)
+  rendered = rendered.replace(/^(\s+ref:)\s+\$\{\{\s*github\.sha\s*\}\}\s*$/gm, `$1 ${ref}`)
+  rendered = rendered.replace(/^(\s+runtime-repository:)\s+.*$/gm, `$1 ${repository}`)
+  rendered = rendered.replace(new RegExp(`^(\\s+repository:)\\s+0xPlayerOne\\/code-foundry\\s*$`, 'gm'), `$1 ${repository}`)
   /** @type {Record<string, string|undefined>} */
   const runners = {
     ci: config.ci_runner ?? config.runner,
@@ -262,6 +308,23 @@ function renderWorkflow(content, config, repository, ref, rustCodeql) {
   if (workflow === 'test' && config.unit_runner) {
     rendered = rendered.replace(/^(\s+unit-runner:)\s+.*$/m, `$1 ${config.unit_runner}`)
   }
+  if (workflow === 'validation') {
+    /** @type {Record<string, string|undefined>} */
+    const runnerInputs = {
+      'ci-runner': config.ci_runner ?? config.runner,
+      'test-runner': config.test_runner ?? config.runner,
+      'security-runner': config.security_runner ?? config.runner,
+      'codeql-runner': config.codeql_runner ?? config.runner,
+      'unit-runner': config.unit_runner,
+    }
+    for (const [input, value] of Object.entries(runnerInputs)) {
+      if (!value) continue
+      rendered = rendered.replace(new RegExp(`^(\\s+${input}:)\\s+.*$`, 'm'), `$1 ${value}`)
+    }
+    rendered = rendered.replace(/^(\s+rust-shards:)\s+.*$/m, `$1 '${rustCodeql.shards}'`)
+    rendered = rendered.replace(/^(\s+rust-threads:)\s+.*$/m, `$1 '${rustCodeql.threads}'`)
+    rendered = rendered.replace(/^(\s+rust-max-parallel:)\s+.*$/m, `$1 ${rustCodeql.maxParallel}`)
+  }
   if (workflow === 'codeql') {
     rendered = rendered.replace(/^(\s+rust-shards:)\s+.*$/m, `$1 '${rustCodeql.shards}'`)
     rendered = rendered.replace(/^(\s+rust-threads:)\s+.*$/m, `$1 '${rustCodeql.threads}'`)
@@ -319,6 +382,27 @@ function validateRustCodeqlConfig(config) {
 /** @param {string} value */
 function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') }
 
+/**
+ * Recognize a Code Foundry-generated legacy event caller (the consumer copies
+ * of the old ci/test/security/codeql callers). Recognition is structural and
+ * end-to-end: the generated name, a thin caller with no steps or runs-on, the
+ * runtime wiring, a single job named after the workflow, and a pinned remote
+ * reference to the runtime's reusable workflow. Anything else is treated as a
+ * repository-owned workflow and preserved byte-for-byte.
+ * @param {string|Buffer} content
+ * @param {string} stem
+ * @param {string} runtimeRepository
+ * @returns {boolean}
+ */
+export function isGeneratedEventCaller(content, stem, runtimeRepository) {
+  const text = Buffer.isBuffer(content) ? content.toString('utf8') : String(content)
+  if (!/^name:\s*Code Foundry\s*$/m.test(text)) return false
+  if (/^\s*(runs-on|steps):/m.test(text)) return false
+  if (!text.includes('runtime-repository:')) return false
+  if (!new RegExp(`^  ${stem}:`, 'm').test(text)) return false
+  return new RegExp(`uses:\\s*${escapeRegExp(runtimeRepository)}/\\.github/workflows/${stem}\\.yml@`).test(text)
+}
+
 /** @param {string} baseline @param {string} existing */
 function mergeGitignore(baseline, existing) {
   const marker = '# Repository-specific rules'

package/src/lib/github-doctor.mjs

@@ -41,12 +41,18 @@ export function doctorGithub(root) {
 
   const secrets = ghJson(['secret', 'list', '--repo', repository, '--json', 'name'])
   const secretNames = Array.isArray(secrets) ? secrets.map(/** @param {any} secret */ (secret) => secret.name) : []
-  details.secrets = { releasePleaseTokenPresent: secretNames.includes('RELEASE_PLEASE_TOKEN') }
-  if (!details.secrets.releasePleaseTokenPresent) warnings.push('RELEASE_PLEASE_TOKEN is not configured; Release Please auto-merge and direct post-release dispatch are unavailable.')
+  details.secrets = {
+    codeFoundryTokenPresent: secretNames.includes('CODE_FOUNDRY_TOKEN'),
+    releasePleaseTokenPresent: secretNames.includes('RELEASE_PLEASE_TOKEN'),
+    stagingDeployKeyPresent: secretNames.includes('STAGING_DEPLOY_KEY'),
+  }
+  if (!details.secrets.codeFoundryTokenPresent && !details.secrets.releasePleaseTokenPresent) {
+    warnings.push('CODE_FOUNDRY_TOKEN and RELEASE_PLEASE_TOKEN are both absent. PR workflow triggers and automation may require manual readiness.')
+  }
 
   const config = readConfig(root)
-  if (['workflow-dispatch', 'dispatch'].includes(config.post_release_mode) && config.post_release !== 'false' && !details.secrets.releasePleaseTokenPresent) {
-    errors.push('post-release workflow-dispatch mode requires RELEASE_PLEASE_TOKEN to be present.')
+  if (['workflow-dispatch', 'dispatch'].includes(config.post_release_mode) && config.post_release !== 'false' && !details.secrets.codeFoundryTokenPresent && !details.secrets.releasePleaseTokenPresent) {
+    errors.push('post-release workflow-dispatch mode requires CODE_FOUNDRY_TOKEN or RELEASE_PLEASE_TOKEN to be present.')
   }
   const credentialChecks = {
     npmTokenPresent: secretNames.includes('NPM_TOKEN'),