code-foundry 0.29.0 → 0.30.0

package/.github/workflows/opencode-security.yml

@@ -0,0 +1,48 @@
+name: Code Foundry
+
+on:
+  pull_request:
+    branches: [staging]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  detect:
+    name: OpenCode Security / Detect
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      startsWith(github.event.pull_request.head.ref, 'release-please--branches--main')
+    runs-on: ubuntu-slim
+    outputs:
+      enabled: ${{ steps.detect.outputs.enabled }}
+      token: ${{ steps.detect.outputs.token }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Detect configuration and token
+        id: detect
+        env:
+          OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
+        run: |
+          enabled=false
+          token=false
+          if grep -Eq '^opencode_security:\s*(true|auto)\s*$' .github/code-foundry.yml 2>/dev/null; then enabled=true; fi
+          if [ -n "$OPENCODE_API_KEY" ]; then token=true; fi
+          echo "enabled=$enabled" >> "$GITHUB_OUTPUT"
+          echo "token=$token" >> "$GITHUB_OUTPUT"
+
+  scan:
+    name: OpenCode Security / Scan
+    needs: detect
+    if: needs.detect.outputs.enabled == 'true' && needs.detect.outputs.token == 'true'
+    uses: 0xPlayerOne/opencode-security/.github/workflows/opencode-security.yml@main
+    with:
+      source_ref: main
+      runner: ubuntu-latest
+      mode: standard
+      fail_on_severity: high
+      max_cost_usd: 1
+    secrets:
+      OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}

package/.github/workflows/opencode-security_self-ci.yml

@@ -0,0 +1,48 @@
+name: Code Foundry
+
+on:
+  pull_request:
+    branches: [staging]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  detect:
+    name: OpenCode Security / Detect
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      startsWith(github.event.pull_request.head.ref, 'release-please--branches--main')
+    runs-on: ubuntu-slim
+    outputs:
+      enabled: ${{ steps.detect.outputs.enabled }}
+      token: ${{ steps.detect.outputs.token }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Detect configuration and token
+        id: detect
+        env:
+          OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
+        run: |
+          enabled=false
+          token=false
+          if grep -Eq '^opencode_security:\s*(true|auto)\s*$' .github/code-foundry.yml 2>/dev/null; then enabled=true; fi
+          if [ -n "$OPENCODE_API_KEY" ]; then token=true; fi
+          echo "enabled=$enabled" >> "$GITHUB_OUTPUT"
+          echo "token=$token" >> "$GITHUB_OUTPUT"
+
+  scan:
+    name: OpenCode Security / Scan
+    needs: detect
+    if: needs.detect.outputs.enabled == 'true' && needs.detect.outputs.token == 'true'
+    uses: 0xPlayerOne/opencode-security/.github/workflows/opencode-security.yml@main
+    with:
+      source_ref: main
+      runner: ubuntu-latest
+      mode: standard
+      fail_on_severity: high
+      max_cost_usd: 1
+    secrets:
+      OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}

package/.github/workflows/release.yml

@@ -20,6 +20,7 @@ on:
         default: v0.27.18
 
 permissions:
+  actions: write
   contents: write
   issues: write
   pull-requests: write
@@ -49,6 +50,13 @@ jobs:
         uses: actions/checkout@v7
         with:
           filter: blob:none
+      - name: Checkout runtime
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ inputs.runtime-repository }}
+          ref: ${{ inputs.runtime-ref }}
+          path: .code-foundry
+          sparse-checkout: src
       - name: Detect release profile
         id: profile
         run: |
@@ -109,43 +117,7 @@ jobs:
           GH_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN }}
         run: |
           set -euo pipefail
-
-          allowed_paths="$(
-            node <<'NODE'
-          const fs = require('node:fs')
-          const config = JSON.parse(fs.readFileSync('release-please-config.json', 'utf8'))
-          const common = [
-            '.release-please-manifest.json',
-            'CHANGELOG.md',
-            'Cargo.lock',
-            'Cargo.toml',
-            'bun.lock',
-            'bun.lockb',
-            'package-lock.json',
-            'package.json',
-            'pnpm-lock.yaml',
-            'pyproject.toml',
-            'uv.lock',
-            'version.txt',
-            'yarn.lock',
-          ]
-          const allowed = new Set(common)
-          const addExtraFiles = (files = [], prefix = '') => {
-            for (const entry of files) {
-              const path = typeof entry === 'string' ? entry : entry.path
-              if (path) allowed.add(prefix ? `${prefix}/${path}` : path)
-            }
-          }
-          addExtraFiles(config['extra-files'])
-          for (const [directory, packageConfig] of Object.entries(config.packages || {})) {
-            const prefix = directory === '.' ? '' : directory.replace(/\/$/, '')
-            for (const path of common) allowed.add(prefix ? `${prefix}/${path}` : path)
-            addExtraFiles(packageConfig['extra-files'], prefix)
-          }
-          process.stdout.write(JSON.stringify([...allowed]))
-          NODE
-          )"
-
+          node .code-foundry/src/cli.mjs release validate-prs
           mapfile -t release_prs < <(
             gh pr list \
               --repo "$GITHUB_REPOSITORY" \
@@ -154,23 +126,7 @@ jobs:
               --json number,title,headRefName \
               --jq '.[] | select(.title | startswith("chore(main): release ")) | select(.headRefName | startswith("release-please--branches--main")) | .number'
           )
-          [ "${#release_prs[@]}" -gt 0 ] || {
-            echo "Release Please reported a pull request, but no generated release PR was found." >&2
-            exit 1
-          }
-
           for pr in "${release_prs[@]}"; do
-            mapfile -t changed_paths < <(gh pr diff "$pr" --repo "$GITHUB_REPOSITORY" --name-only)
-            [ "${#changed_paths[@]}" -gt 0 ] || {
-              echo "Generated release PR #$pr has no changed files." >&2
-              exit 1
-            }
-            for path in "${changed_paths[@]}"; do
-              jq -e --arg path "$path" 'index($path) != null' <<<"$allowed_paths" >/dev/null || {
-                echo "Refusing to auto-merge release PR #$pr with unexpected path: $path" >&2
-                exit 1
-              }
-            done
             gh pr merge "$pr" \
               --repo "$GITHUB_REPOSITORY" \
               --admin \
@@ -219,6 +175,57 @@ jobs:
         if: steps.staging.outputs.exists != 'true'
         run: echo 'No staging branch exists; release reconciliation is not applicable.'
 
+  post-release:
+    name: Release / Post Hook
+    needs: release
+    if: needs.release.outputs.release_created == 'true'
+    runs-on: ${{ inputs.runner }}
+    timeout-minutes: 15
+    concurrency:
+      group: code-foundry-post-release-${{ github.repository }}-${{ needs.release.outputs.tag_name }}
+      cancel-in-progress: false
+    permissions:
+      actions: write
+      contents: read
+    env:
+      RELEASE_PLEASE_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.release.outputs.tag_name }}
+          filter: blob:none
+      - name: Checkout runtime
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ inputs.runtime-repository }}
+          ref: ${{ inputs.runtime-ref }}
+          path: .code-foundry
+          sparse-checkout: src
+      - name: Detect post-release hook
+        id: hook
+        run: |
+          node <<'NODE' >> "$GITHUB_OUTPUT"
+          const fs = require('node:fs')
+          const file = '.github/code-foundry.yml'
+          const config = fs.existsSync(file)
+            ? Object.fromEntries(fs.readFileSync(file, 'utf8').split(/\r?\n/).flatMap((line) => {
+                const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/)
+                return match ? [[match[1], match[2].replace(/\s+#.*$/, '').replace(/^['"]|['"]$/g, '')]] : []
+              }))
+            : {}
+          const enabled = ['true', 'auto'].includes(config.post_release ?? 'false')
+          console.log(`enabled=${enabled}`)
+          console.log(`workflow=${config.post_release_workflow ?? ''}`)
+          console.log(`mode=${config.post_release_mode ?? 'auto'}`)
+          NODE
+      - name: Dispatch post-release hook once
+        if: steps.hook.outputs.enabled == 'true' && steps.hook.outputs.workflow != ''
+        run: node .code-foundry/src/cli.mjs release hook --tag '${{ needs.release.outputs.tag_name }}' --workflow '${{ steps.hook.outputs.workflow }}' --mode '${{ steps.hook.outputs.mode }}'
+      - name: Explain disabled post-release hook
+        if: steps.hook.outputs.enabled != 'true' || steps.hook.outputs.workflow == ''
+        run: echo 'No post-release workflow configured; artifact delivery is intentionally skipped.'
+
   npm:
     name: Release / Publish npm
     needs: release

package/.github/workflows/release_self-ci.yml

@@ -6,6 +6,7 @@ on:
   workflow_dispatch:
 
 permissions:
+  actions: write
   contents: write
   issues: write
   pull-requests: write
@@ -18,5 +19,5 @@ jobs:
     with:
       runner: ubuntu-slim
       runtime-repository: 0xPlayerOne/code-foundry
-      runtime-ref: v0.27.18
+      runtime-ref: main
     secrets: inherit

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.30.0](https://github.com/0xPlayerOne/code-foundry/compare/v0.29.0...v0.30.0) (2026-07-29)
+
+
+### Features
+
+* **ci:** recommend stack-aware runners ([83df327](https://github.com/0xPlayerOne/code-foundry/commit/83df32777344898651d71af28496202337ae6788))
+* **doctor:** validate GitHub release configuration ([877525c](https://github.com/0xPlayerOne/code-foundry/commit/877525c11f6713b235aa3945dd98d017bef5732e))
+* **fleet:** add isolated repository upgrades ([76d1765](https://github.com/0xPlayerOne/code-foundry/commit/76d176593ea025a2090bd62f21b275d261d3a9d5))
+* **release:** add exactly-once post-release hooks ([f4ffa13](https://github.com/0xPlayerOne/code-foundry/commit/f4ffa136ef972665fe269b6685f9c4b840fc95a9))
+* **release:** add non-destructive recovery planning ([6c45592](https://github.com/0xPlayerOne/code-foundry/commit/6c45592358d9ceb0335acc6584ac565971433737))
+* **security:** add opt-in OpenCode release scan ([34512c1](https://github.com/0xPlayerOne/code-foundry/commit/34512c1507519d2b37a9bd665243490fa888beb9))
+* **sync:** formalize custom workflow overlays ([ee540f9](https://github.com/0xPlayerOne/code-foundry/commit/ee540f9a80c0b128100e795471042fc12aefc226))
+
+
+### Bug Fixes
+
+* **release:** grant post-release dispatch permission ([c18a52d](https://github.com/0xPlayerOne/code-foundry/commit/c18a52dff2ac76e648eeb9fa1f92fab8a01dafec))
+
 ## [0.29.0](https://github.com/0xPlayerOne/code-foundry/compare/v0.28.0...v0.29.0) (2026-07-29)
 
 

package/docs/EXTENSIONS.md

@@ -0,0 +1,19 @@
+# Code Foundry extension points
+
+Code Foundry uses an overlay model. The files in its documented baseline are managed by `sync`; repository-owned files outside that baseline remain yours.
+
+## Managed files
+
+The standard workflows, hooks, governance documents, language configuration, and release configuration are refreshed from the configured runtime. Keep repository-specific behavior in separate files.
+
+## Custom workflows
+
+Any workflow not named by the baseline is preserved automatically. This is the supported place for project-specific workflows such as Slither, search indexing, deployment, Docker publishing, or Vercel tasks.
+
+Set `custom_workflows: preserve` in `.github/code-foundry.yml` (the default). Code Foundry intentionally has no prune mode for custom workflows; remove those files explicitly when they are no longer needed.
+
+## Release and deployment hooks
+
+Use `post_release`, `post_release_workflow`, and `post_release_mode` for a post-release artifact workflow. The hook receives `release-tag` and `delivery-key` inputs and is dispatched at most once per tag when a release token is available.
+
+Keep deployment credentials, environment files, and project-specific secrets in the repository or organization configuration. Code Foundry never copies secret values or overwrites custom workflows in overlay mode.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "A fast, language-aware repository factory for agent-ready workflows, testing, security, and release automation.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package/src/cli.mjs

@@ -2,14 +2,16 @@
 // @ts-check
 
 import { resolve } from 'node:path'
+import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { doctor } from './commands/doctor.mjs'
-import { reconcileRelease } from './commands/release.mjs'
+import { dispatchPostReleaseHook, reconcileRelease, releaseRecoveryPlan, validateReleasePullRequestDiffs } from './commands/release.mjs'
+import { discoverRepositories, upgradeFleet } from './commands/fleet.mjs'
 import { syncRepository } from './commands/sync.mjs'
 
 const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)))
 
-/** @typedef {{ target: string, dryRun: boolean, force: boolean, github: boolean, base: string, head: string }} Options */
+/** @typedef {{ target: string, root: string, dryRun: boolean, force: boolean, github: boolean, createPr: boolean, base: string, head: string, tag: string, workflow: string, mode: string, version: string, releaseSubcommand?: string, fleetSubcommand?: string }} Options */
 /** @typedef {{ command: string, options: Options }} ParsedArgs */
 
 const usage = `code-foundry — initialize and maintain agent-ready repositories
@@ -19,6 +21,9 @@ Usage:
   npx code-foundry sync [--target PATH]
   npx code-foundry doctor [--target PATH]
   npx code-foundry release reconcile [--github] [--base BRANCH] [--head BRANCH]
+  npx code-foundry release hook --tag TAG --workflow WORKFLOW
+  npx code-foundry fleet status [--root PATH]
+  npx code-foundry fleet upgrade [--root PATH] [--dry-run] [--create-pr]
 
 The repository configuration lives in .github/code-foundry.yml.
 init detects the repository, creates that file, and renders the baseline.
@@ -31,6 +36,12 @@ Options:
   --github        Apply a verified fast-forward through GitHub
   --base BRANCH   Release source branch (default: main)
   --head BRANCH   Branch to reconcile (default: staging)
+  --tag TAG       Published release tag for a post-release hook
+  --workflow FILE  Workflow to dispatch for a post-release hook
+  --mode MODE     auto, workflow-dispatch, release-event, or disabled
+  --root PATH     Fleet root containing repositories (default: current directory)
+  --create-pr     Create isolated upgrade branches and pull requests
+  --version TAG   Runtime tag to report in fleet upgrade branches
   -h, --help      Show this help
 `
 
@@ -45,11 +56,17 @@ function parseArgs(argv) {
   const first = argv[0]
   const hasCommand = Boolean(first && !first.startsWith('-'))
   const command = hasCommand ? /** @type {string} */ (argv.shift()) : 'init'
-  const options = { target: process.cwd(), dryRun: false, force: false, github: false, base: 'main', head: 'staging' }
+  /** @type {Options} */
+  const options = { target: process.cwd(), root: process.cwd(), dryRun: false, force: false, github: false, createPr: false, base: 'main', head: 'staging', tag: '', workflow: '', mode: 'auto', version: `v${readPackageVersion(packageRoot)}` }
 
   if (command === 'release') {
-    const subcommand = argv.shift()
-    if (subcommand !== 'reconcile') fail(`unknown release command: ${subcommand ?? '(missing)'}; use release reconcile`)
+    const subcommand = argv.shift() ?? ''
+    if (!['reconcile', 'hook', 'validate-prs', 'recovery-plan'].includes(subcommand)) fail(`unknown release command: ${subcommand ?? '(missing)'}; use release reconcile, release hook, release validate-prs, or release recovery-plan`)
+    options.releaseSubcommand = subcommand
+  } else if (command === 'fleet') {
+    const subcommand = argv.shift() ?? ''
+    if (subcommand !== 'status' && subcommand !== 'upgrade') fail(`unknown fleet command: ${subcommand ?? '(missing)'}; use fleet status or fleet upgrade`)
+    options.fleetSubcommand = subcommand
   }
 
   while (argv.length) {
@@ -67,6 +84,12 @@ function parseArgs(argv) {
     else if (arg === '--github') options.github = true
     else if (arg === '--base') options.base = argv.shift() ?? fail('--base requires a branch')
     else if (arg === '--head') options.head = argv.shift() ?? fail('--head requires a branch')
+    else if (arg === '--tag') options.tag = argv.shift() ?? fail('--tag requires a tag')
+    else if (arg === '--workflow') options.workflow = argv.shift() ?? fail('--workflow requires a workflow')
+    else if (arg === '--mode') options.mode = argv.shift() ?? fail('--mode requires a delivery mode')
+    else if (arg === '--root') options.root = argv.shift() ?? fail('--root requires a path')
+    else if (arg === '--create-pr') options.createPr = true
+    else if (arg === '--version') options.version = argv.shift() ?? fail('--version requires a tag')
     else fail(`unknown option: ${arg}; run --help for the supported options`)
   }
 
@@ -91,14 +114,25 @@ function main() {
     }
   } else if (command === 'doctor') {
     try {
-      doctor(target)
+      doctor(target, { github: options.github })
     } catch (error) {
       console.error(`code-foundry: ${error instanceof Error ? error.message : String(error)}`)
       process.exitCode = 1
     }
   } else if (command === 'release') {
     try {
-      reconcileRelease(target, options)
+      if (options.releaseSubcommand === 'hook') dispatchPostReleaseHook(target, options)
+      else if (options.releaseSubcommand === 'validate-prs') validateReleasePullRequestDiffs(target)
+      else if (options.releaseSubcommand === 'recovery-plan') releaseRecoveryPlan(target)
+      else reconcileRelease(target, options)
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error))
+    }
+  } else if (command === 'fleet') {
+    try {
+      const root = resolve(options.root)
+      if (options.fleetSubcommand === 'status') console.log(JSON.stringify(discoverRepositories(root), null, 2))
+      else upgradeFleet(root, packageRoot, { createPr: options.createPr, dryRun: options.dryRun, force: options.force, version: options.version })
     } catch (error) {
       fail(error instanceof Error ? error.message : String(error))
     }
@@ -107,3 +141,8 @@ function main() {
 }
 
 main()
+
+/** @param {string} root @returns {string} */
+function readPackageVersion(root) {
+  try { return JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8')).version ?? '0.0.0' } catch { return '0.0.0' }
+}

package/src/commands/doctor.mjs

@@ -4,13 +4,15 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { includesValue, readConfig } from '../lib/config.mjs'
-import { resolveProfile } from '../lib/profile.mjs'
+import { recommendRunners, resolveProfile } from '../lib/profile.mjs'
+import { doctorGithub } from '../lib/github-doctor.mjs'
 
-/** @param {string} root */
-export function doctor(root) {
+/** @param {string} root @param {{ github?: boolean }} [options] */
+export function doctor(root, options = {}) {
   const target = resolve(root)
   const config = readConfig(join(target, '.github/code-foundry.yml'))
   const profile = resolveProfile(target)
+  const recommendations = recommendRunners(target)
   let errors = 0
   /** @param {string} message */
   const error = (message) => { console.error(`ERROR: ${message}`); errors += 1 }
@@ -27,6 +29,9 @@ export function doctor(root) {
   }
   const hooks = git(target, ['config', '--get', 'core.hooksPath'])
   if (hooks !== '.githooks') warn('Git hooks are not enabled; run `npx code-foundry init`')
+  if (['rust', 'python', 'solidity'].some((language) => profile.languages.split(',').includes(language)) && (config.unit_runner ?? recommendations.unit_runner) === 'ubuntu-slim') {
+    warn('unit_runner is ubuntu-slim for a native-toolchain repository; ubuntu-latest is recommended.')
+  }
 
   const packageFile = join(target, 'package.json')
   if (existsSync(packageFile)) {
@@ -55,6 +60,12 @@ export function doctor(root) {
     if (includesValue(config.features ?? 'all', workflow) && !existsSync(join(target, `.github/workflows/${workflow}.yml`))) error(`missing enabled workflow: ${workflow}.yml`)
   }
   console.log('Remote CI, Test, Security, CodeQL, and release runtimes are loaded by reusable workflow wrappers.')
+  if (options.github) {
+    const github = doctorGithub(target)
+    for (const message of github.warnings) warn(`GitHub: ${message}`)
+    for (const message of github.errors) error(`GitHub: ${message}`)
+    console.log(`GitHub doctor inspected ${github.details.repository}.`)
+  }
   if (errors) throw new Error(`Repository doctor found ${errors} error(s).`)
   console.log('Repository doctor passed.')
 }

package/src/commands/fleet.mjs

@@ -0,0 +1,111 @@
+// @ts-check
+
+import { existsSync, mkdtempSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { spawnSync } from 'node:child_process'
+import { syncRepository } from './sync.mjs'
+
+/** @typedef {{ path: string, repository: string, runtimeRef: string, dirty: boolean, configured: boolean }} FleetRepository */
+
+/** @param {string} root @returns {FleetRepository[]} */
+export function discoverRepositories(root) {
+  /** @type {FleetRepository[]} */
+  const result = []
+  const candidates = [root, ...children(root), ...children(join(root, 'NiftyLeague'))]
+  for (const candidate of [...new Set(candidates)]) {
+    if (!existsSync(join(candidate, '.git'))) continue
+    const configured = existsSync(join(candidate, '.github/code-foundry.yml'))
+    const config = readConfig(join(candidate, '.github/code-foundry.yml'))
+    const remote = git(candidate, ['remote', 'get-url', 'origin'])
+    result.push({
+      path: candidate,
+      repository: normalizeRemote(remote),
+      runtimeRef: config.runtime_ref ?? '',
+      dirty: Boolean(git(candidate, ['status', '--porcelain'])),
+      configured,
+    })
+  }
+  return result.sort((a, b) => a.path.localeCompare(b.path))
+}
+
+/** @param {string} root @param {string} source @param {{ createPr?: boolean, dryRun?: boolean, force?: boolean, version: string }} options */
+export function upgradeFleet(root, source, options) {
+  const repositories = discoverRepositories(root)
+  const report = []
+  for (const repository of repositories) {
+    if (!repository.configured) {
+      report.push({ path: repository.path, status: 'skipped', reason: 'missing .github/code-foundry.yml' })
+      continue
+    }
+    if (repository.dirty && !options.force) {
+      report.push({ path: repository.path, status: 'skipped', reason: 'working tree is dirty' })
+      continue
+    }
+    if (!options.createPr || options.dryRun) {
+      const result = syncRepository({ target: repository.path, source, dryRun: options.dryRun, force: false })
+      report.push({ path: repository.path, status: options.dryRun ? 'preview' : 'synced', changed: result.changed })
+      continue
+    }
+    if (!repository.repository) {
+      report.push({ path: repository.path, status: 'skipped', reason: 'origin is not a GitHub remote' })
+      continue
+    }
+    report.push(upgradeRepository(repository, source, options.version))
+  }
+  console.log(JSON.stringify(report, null, 2))
+  return report
+}
+
+/** @param {FleetRepository} repository @param {string} source @param {string} version */
+function upgradeRepository(repository, source, version) {
+  const branch = `codex/code-foundry-upgrade-${version.replace(/^v/, '')}`
+  const temporary = mkdtempSync(join(tmpdir(), 'code-foundry-fleet-'))
+  try {
+    const add = spawnSync('git', ['-C', repository.path, 'worktree', 'add', '-b', branch, temporary, 'HEAD'], { encoding: 'utf8' })
+    if (add.status !== 0) return { path: repository.path, status: 'skipped', reason: add.stderr.trim() || 'unable to create isolated worktree' }
+    const result = syncRepository({ target: temporary, source, force: false })
+    if (!result.changed.length) return { path: repository.path, status: 'unchanged', branch }
+    spawnSync('git', ['-C', temporary, 'add', '-A'], { stdio: 'ignore' })
+    const commit = spawnSync('git', ['-C', temporary, 'commit', '-m', `chore(code-foundry): upgrade runtime to ${version}`], { encoding: 'utf8' })
+    if (commit.status !== 0) return { path: repository.path, status: 'failed', reason: commit.stderr.trim() || 'commit failed' }
+    const push = spawnSync('git', ['-C', temporary, 'push', '-u', 'origin', branch], { encoding: 'utf8' })
+    if (push.status !== 0) return { path: repository.path, status: 'failed', reason: push.stderr.trim() || 'push failed' }
+    const pr = spawnSync('gh', ['pr', 'create', '--repo', repository.repository, '--base', 'staging', '--head', branch, '--title', `chore(code-foundry): upgrade to ${version}`, '--body', `Automated isolated Code Foundry runtime upgrade to ${version}.\n\nThe sync preserved protected repository-owned documents and custom workflows.`], { encoding: 'utf8' })
+    return pr.status === 0
+      ? { path: repository.path, status: 'pr-created', branch, pullRequest: pr.stdout.trim() }
+      : { path: repository.path, status: 'failed', branch, reason: pr.stderr.trim() || 'pull request creation failed' }
+  } finally {
+    spawnSync('git', ['-C', repository.path, 'worktree', 'remove', '--force', temporary], { stdio: 'ignore' })
+  }
+}
+
+/** @param {string} root @returns {string[]} */
+function children(root) {
+  try {
+    return readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.') && !['node_modules', 'target'].includes(entry.name))
+      .map((entry) => join(root, entry.name))
+  } catch { return [] }
+}
+
+/** @param {string} file @returns {Record<string, string>} */
+function readConfig(file) {
+  try {
+    return Object.fromEntries(requireText(file).split(/\r?\n/).flatMap((line) => {
+      const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/)
+      return match ? [[match[1], match[2].replace(/\s+#.*$/, '').replace(/^['"]|['"]$/g, '')]] : []
+    }))
+  } catch { return {} }
+}
+
+/** @param {string} file */
+function requireText(file) {
+  return readFileSync(file, 'utf8')
+}
+
+/** @param {string} root @param {string[]} args */
+function git(root, args) { return spawnSync('git', args, { cwd: root, encoding: 'utf8' }).stdout?.trim() ?? '' }
+
+/** @param {string} remote */
+function normalizeRemote(remote) { return remote.replace(/^git@github\.com:/, '').replace(/^https?:\/\/github\.com\//, '').replace(/\.git$/, '') }

package/src/commands/release.mjs

@@ -1,9 +1,10 @@
 // @ts-check
 
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { approvedReleaseFiles, classifyReconciliation, readReleaseConfig } from '../lib/release-policy.mjs'
+import { approvedReleaseFiles, buildReleaseRecoveryPlan, classifyReconciliation, readReleaseConfig, selectGeneratedReleasePrs, validateReleasePullRequests } from '../lib/release-policy.mjs'
+import { hasDeliveredHook, releaseDeliveryKey, selectHookDelivery } from '../lib/release-hook.mjs'
 
 /** @typedef {{ target: string, dryRun: boolean, github: boolean, base: string, head: string }} ReleaseOptions */
 
@@ -45,6 +46,75 @@ export function reconcileRelease(root, options) {
   return plan
 }
 
+/**
+ * Dispatch a configured post-release workflow at most once for a tag.
+ * @param {string} root
+ * @param {{ tag: string, workflow: string, mode?: string, dryRun?: boolean }} options
+ */
+export function dispatchPostReleaseHook(root, options) {
+  const repository = process.env.GITHUB_REPOSITORY
+  if (!repository) throw new Error('GITHUB_REPOSITORY is required for post-release hooks.')
+  if (!options.tag) throw new Error('--tag is required for post-release hooks.')
+  const decision = selectHookDelivery({ mode: options.mode, tokenPresent: Boolean(process.env.RELEASE_PLEASE_TOKEN) })
+  console.log(JSON.stringify({ repository, tag: options.tag, workflow: options.workflow, ...decision }, null, 2))
+  if (decision.delivery === 'disabled' || decision.delivery === 'release-event') return decision
+  if (decision.delivery === 'unavailable') throw new Error(decision.reason)
+  if (!options.workflow) throw new Error('--workflow is required for workflow-dispatch hooks.')
+  const key = releaseDeliveryKey(repository, options.tag)
+  const runs = ghJson(root, ['run', 'list', '--repo', repository, '--workflow', options.workflow, '--limit', '100', '--json', 'headBranch,displayTitle,status'])
+  if (hasDeliveredHook(Array.isArray(runs) ? runs : [], options.tag)) {
+    console.log(`Post-release hook already delivered for ${options.tag}; skipping duplicate dispatch.`)
+    return { ...decision, deliveryKey: key, skipped: true }
+  }
+  if (options.dryRun) return { ...decision, deliveryKey: key, dispatched: false }
+  const result = spawnSync('gh', [
+    'workflow', 'run', options.workflow,
+    '--repo', repository,
+    '--ref', options.tag,
+    '--field', `release-tag=${options.tag}`,
+    '--field', `delivery-key=${key}`,
+  ], { cwd: resolve(root), stdio: 'inherit', env: { ...process.env, GH_TOKEN: process.env.RELEASE_PLEASE_TOKEN } })
+  if (result.status !== 0) throw new Error(`Failed to dispatch post-release workflow ${options.workflow}.`)
+  return { ...decision, deliveryKey: key, dispatched: true }
+}
+
+/** @param {string} root */
+export function validateReleasePullRequestDiffs(root) {
+  const repository = process.env.GITHUB_REPOSITORY
+  if (!repository) throw new Error('GITHUB_REPOSITORY is required for release PR validation.')
+  const prs = ghJson(root, ['pr', 'list', '--repo', repository, '--state', 'open', '--base', 'main', '--json', 'number,title,headRefName'])
+  const generated = selectGeneratedReleasePrs(Array.isArray(prs) ? prs : [])
+  /** @type {Map<number, string[]>} */
+  const paths = new Map()
+  for (const pr of generated) {
+    const number = Number(pr.number)
+    const result = spawnSync('gh', ['pr', 'diff', String(number), '--repo', repository, '--name-only'], { cwd: resolve(root), encoding: 'utf8' })
+    paths.set(number, result.status === 0 ? result.stdout.split(/\r?\n/).filter(Boolean) : [])
+  }
+  const validation = validateReleasePullRequests(Array.isArray(prs) ? prs : [], paths, approvedReleaseFiles(readReleaseConfig(root)))
+  console.log(JSON.stringify(validation, null, 2))
+  if (!validation.valid) throw new Error(validation.errors.join(' '))
+  return validation
+}
+
+/** @param {string} root */
+export function releaseRecoveryPlan(root) {
+  const repository = process.env.GITHUB_REPOSITORY
+  if (!repository) throw new Error('GITHUB_REPOSITORY is required for release recovery planning.')
+  const tags = ghJson(root, ['api', `repos/${repository}/tags?per_page=100`])
+  const releases = ghJson(root, ['release', 'list', '--repo', repository, '--limit', '100', '--json', 'tagName,name,isDraft,isPrerelease'])
+  const releasePrs = ghJson(root, ['pr', 'list', '--repo', repository, '--state', 'open', '--base', 'main', '--json', 'number,title'])
+  const packageVersions = localPackageVersions(root)
+  const plan = buildReleaseRecoveryPlan({
+    tags: Array.isArray(tags) ? tags.map((tag) => tag.name).filter(Boolean) : [],
+    releases: Array.isArray(releases) ? releases : [],
+    releasePrs: Array.isArray(releasePrs) ? releasePrs.filter((pr) => /^chore\(main\): release /.test(pr.title ?? '')) : [],
+    packageVersions,
+  })
+  console.log(JSON.stringify(plan, null, 2))
+  return plan
+}
+
 /** @param {string} root @param {string[]} args @returns {string} */
 function git(root, args) {
   const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' })
@@ -58,6 +128,32 @@ function diffNames(root, from, to) {
   return result.status === 0 ? result.stdout.split(/\r?\n/).filter(Boolean) : []
 }
 
+/** @param {string} root @param {string[]} args @returns {unknown} */
+function ghJson(root, args) {
+  const result = spawnSync('gh', args, { cwd: resolve(root), encoding: 'utf8', env: { ...process.env, GH_TOKEN: process.env.RELEASE_PLEASE_TOKEN } })
+  if (result.status !== 0) return []
+  try { return JSON.parse(result.stdout) }
+  catch { return [] }
+}
+
+/** @param {string} root @returns {string[]} */
+function localPackageVersions(root) {
+  const versions = []
+  const packageJson = join(resolve(root), 'package.json')
+  if (existsSync(packageJson)) {
+    try { versions.push(JSON.parse(readFileSync(packageJson, 'utf8')).version) } catch { /* doctor handles malformed manifests */ }
+  }
+  /** @type {Array<[string, RegExp]>} */
+  const manifests = [['Cargo.toml', /^version\s*=\s*["']([^"']+)["']/m], ['pyproject.toml', /^(?:version|version\s*)\s*=\s*["']([^"']+)["']/m]]
+  for (const [file, pattern] of manifests) {
+    const path = join(resolve(root), file)
+    if (!existsSync(path)) continue
+    const match = readFileSync(path, 'utf8').match(pattern)
+    if (match?.[1]) versions.push(match[1])
+  }
+  return versions.filter(Boolean)
+}
+
 /** @param {string} root */
 export function releaseConfigExists(root) {
   return existsSync(join(resolve(root), 'release-please-config.json'))

package/src/commands/sync.mjs

@@ -3,12 +3,14 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { detectLanguages, detectPackageManager, detectProfile } from '../lib/profile.mjs'
+import { detectLanguages, detectPackageManager, detectProfile, recommendRunners } from '../lib/profile.mjs'
 import { configured, includesValue, readConfig } from '../lib/config.mjs'
 import { buildReleaseConfig } from '../lib/release-manifest.mjs'
+import { customWorkflowFiles, overlayPolicy } from '../lib/overlay.mjs'
 
 const standardFiles = [
   '.editorconfig', '.gitattributes', '.gitignore', 'release-please-config.json',
+  'docs/EXTENSIONS.md',
   '.githooks/pre-commit', 'AGENTS.md', 'LICENSE', 'NOTICE', 'ruff.toml', '.prettierrc',
   '.github/CODEOWNERS', '.github/CODE_OF_CONDUCT.md', '.github/CONTRIBUTING.md',
   '.github/PULL_REQUEST_TEMPLATE.md', '.github/SECURITY.md', '.github/dependabot.yml',
@@ -16,7 +18,7 @@ const standardFiles = [
   '.github/ISSUE_TEMPLATE/feature_request.yml',
   '.github/workflows/ci.yml', '.github/workflows/codeql.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/security.yml', '.github/workflows/test.yml', '.github/workflows/opencode-security.yml',
 ]
 
 const protectedFiles = new Set([
@@ -64,6 +66,7 @@ export function syncRepository(options) {
   const runtimeRepository = configured(config.runtime_repository, '0xPlayerOne/code-foundry')
   const runtimeRef = configured(config.runtime_ref, `v${readPackageVersion(source)}`)
   const toolchain = configured(config.toolchain, 'auto')
+  const overlays = overlayPolicy(target, config)
   if (!['auto', 'native', 'mise'].includes(toolchain)) {
     throw new Error(`Unsupported toolchain: ${toolchain}; use auto, native, or mise.`)
   }
@@ -71,7 +74,7 @@ export function syncRepository(options) {
   const changed = []
 
   for (const file of standardFiles) {
-    if (!shouldInclude(file, languages, features)) continue
+    if (!shouldInclude(file, languages, features, config)) continue
     const sourceFile = sourcePath(source, file)
     if (!existsSync(sourceFile)) throw new Error(`Template file missing: ${file}`)
     const destination = join(target, file)
@@ -134,6 +137,10 @@ export function syncRepository(options) {
     git(target, ['config', 'core.hooksPath', '.githooks'])
   }
   console.log(`${changed.length} baseline file(s) differ.`)
+  if (overlays.custom_workflows === 'preserve') {
+    const custom = customWorkflowFiles(target, standardFiles)
+    if (custom.length) console.log(`Preserved ${custom.length} repository-owned workflow(s).`)
+  }
   return { changed, config }
 }
 
@@ -152,11 +159,12 @@ function renderReleaseConfig(target, sourceFile) {
   return `${JSON.stringify(buildReleaseConfig(target, merged), null, 2)}\n`
 }
 
-/** @param {string} file @param {string} languages @param {string} features */
-function shouldInclude(file, languages, features) {
+/** @param {string} file @param {string} languages @param {string} features @param {Record<string, string>} config */
+function shouldInclude(file, languages, features, config) {
   if (file === 'ruff.toml') return includesValue(languages, 'python')
   if (file === '.prettierrc') return includesValue(languages, 'typescript')
   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]
   return !workflow || includesValue(features, workflow)
 }
@@ -235,14 +243,17 @@ function buffersEqual(a, b) { return a.equals(b) }
 function createDefaultConfig(root, source) {
   const languages = detectLanguages(root).join(',')
   const packageManager = detectPackageManager(root)
+  const runners = recommendRunners(root)
   return {
     version: '1', profile: detectProfile(root), languages, features: 'all', codeql: 'auto', dependency_review: 'auto', package_manager: packageManager,
     runtime_repository: '0xPlayerOne/code-foundry', runtime_ref: `v${readPackageVersion(source)}`,
-    runner: 'ubuntu-latest', unit_runner: 'ubuntu-slim', ci_runner: 'ubuntu-latest', test_runner: 'ubuntu-latest',
+    ...runners,
     toolchain: 'auto',
-    security_runner: 'ubuntu-slim', codeql_runner: 'ubuntu-latest', pr_runner: 'ubuntu-slim', release_runner: 'ubuntu-slim',
     prune_standard: 'false', cache_packages: 'auto', cache_build: 'auto', coverage_minimum: '80', turbo_remote: 'auto',
     release_type: detectPackageManager(root) === 'none' ? 'auto' : 'node', npm_publish: 'false',
+    post_release: 'false', post_release_workflow: '', post_release_mode: 'auto',
+    opencode_security: 'false',
+    sync_mode: 'overlay', custom_workflows: 'preserve',
     license: existsSync(join(root, 'LICENSE')) ? 'preserve' : 'gpl-3.0-or-later', git_workflow: 'staging-release', merge_strategy: 'rebase',
   }
 }

package/src/lib/github-doctor.mjs

@@ -0,0 +1,114 @@
+// @ts-check
+
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+/** @param {string} root @returns {{ errors: string[], warnings: string[], details: Record<string, unknown> }} */
+export function doctorGithub(root) {
+  const repository = process.env.GITHUB_REPOSITORY || remoteRepository(root)
+  if (!repository) throw new Error('Unable to determine GitHub repository; set GITHUB_REPOSITORY.')
+  if (!commandExists('gh')) throw new Error('GitHub-aware doctor requires the `gh` CLI.')
+  /** @type {string[]} */
+  const errors = []
+  /** @type {string[]} */
+  const warnings = []
+  /** @type {Record<string, any>} */
+  const details = { repository }
+  const protection = ghJson(['api', `repos/${repository}/branches/main/protection`])
+  if (!protection) warnings.push('main branch protection is not readable or is not configured.')
+  else {
+    const required = [
+      ...(protection.required_status_checks?.contexts ?? []),
+      ...(protection.required_status_checks?.checks ?? []).map(/** @param {any} check */ (check) => check.context),
+    ].filter(Boolean)
+    details.requiredChecks = required
+    const duplicateNames = required.filter((name) => /\b([^/]+) \/ \1\b/i.test(name))
+    if (duplicateNames.length) errors.push(`required checks contain duplicate workflow prefixes: ${duplicateNames.join(', ')}`)
+    if (!protection.required_status_checks) warnings.push('main protection has no required status checks.')
+  }
+
+  const sha = String(ghJson(['api', `repos/${repository}/git/ref/heads/main`])?.object?.sha ?? '')
+  const checks = sha ? ghJson(['api', `repos/${repository}/commits/${sha}/check-runs?per_page=100`])?.check_runs ?? [] : []
+  const observed = checks.map(/** @param {any} check */ (check) => check.name).filter(Boolean)
+  details.observedChecks = observed
+  if (!observed.length) warnings.push('no check runs were observed on the current main commit; exact check validation is deferred until CI runs.')
+  if (protection?.required_status_checks) {
+    const required = [
+      ...(protection.required_status_checks.contexts ?? []),
+      ...(protection.required_status_checks.checks ?? []).map(/** @param {any} check */ (check) => check.context),
+    ].filter(Boolean)
+    const missing = required.filter((name) => observed.length && !observed.includes(name))
+    if (missing.length) warnings.push(`required checks not observed on current main: ${missing.join(', ')}`)
+  }
+
+  const workflowIssues = inspectWorkflows(root)
+  errors.push(...workflowIssues.errors)
+  warnings.push(...workflowIssues.warnings)
+
+  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.')
+
+  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.')
+  }
+
+  const prs = ghJson(['pr', 'list', '--repo', repository, '--state', 'open', '--base', 'main', '--json', 'number,title,headRefName'])
+  const openPrs = Array.isArray(prs) ? prs : []
+  details.openPromotionPrs = openPrs.filter(/** @param {any} pr */ (pr) => pr.headRefName === 'staging' || /promote staging/i.test(pr.title))
+  details.openReleasePrs = openPrs.filter(/** @param {any} pr */ (pr) => String(pr.headRefName).startsWith('release-please--') || /^chore\(main\): release /.test(pr.title))
+  if (details.openPromotionPrs.length > 1) errors.push('multiple staging promotion PRs are open.')
+  if (details.openReleasePrs.length > 1) errors.push('multiple Release Please PRs are open.')
+  return { errors, warnings, details }
+}
+
+/** @param {string} root @returns {{ errors: string[], warnings: string[] }} */
+function inspectWorkflows(root) {
+  /** @type {string[]} */
+  const errors = []
+  /** @type {string[]} */
+  const warnings = []
+  const directory = join(root, '.github/workflows')
+  /** @type {string[]} */
+  let files = []
+  try { files = readdirSync(directory).filter((file) => file.endsWith('.yml') || file.endsWith('.yaml')) }
+  catch { return { errors: ['.github/workflows is missing.'], warnings } }
+  for (const file of files) {
+    const content = readFileSync(join(directory, file), 'utf8')
+    if (!/^permissions:\s*$/m.test(content) && /uses:.*\.github\/workflows\//.test(content)) warnings.push(`${file} does not declare top-level permissions.`)
+    if (file === 'release.yml' && /contents:\s+write/.test(content) && !/pull-requests:\s+write/.test(content)) errors.push('release.yml needs pull-requests: write for guarded Release Please PR handling.')
+  }
+  return { errors, warnings }
+}
+
+/** @param {string} root @returns {string} */
+function remoteRepository(root) {
+  const result = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: root, encoding: 'utf8' })
+  const value = result.status === 0 ? result.stdout.trim() : ''
+  return value.replace(/^git@github\.com:/, '').replace(/^https?:\/\/github\.com\//, '').replace(/\.git$/, '')
+}
+
+/** @param {string[]} args @returns {any} */
+function ghJson(args) {
+  const result = spawnSync('gh', args, { encoding: 'utf8' })
+  if (result.status !== 0) return null
+  try { return JSON.parse(result.stdout) }
+  catch { return null }
+}
+
+/** @param {string} command */
+function commandExists(command) { return spawnSync(command, ['--version'], { stdio: 'ignore' }).status === 0 }
+
+/** @param {string} root @returns {Record<string, string>} */
+function readConfig(root) {
+  const file = join(root, '.github/code-foundry.yml')
+  try {
+    return Object.fromEntries(readFileSync(file, 'utf8').split(/\r?\n/).flatMap((line) => {
+      const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/)
+      return match ? [[match[1], match[2].replace(/\s+#.*$/, '').replace(/^['"]|['"]$/g, '')]] : []
+    }))
+  } catch { return {} }
+}

package/src/lib/overlay.mjs

@@ -0,0 +1,29 @@
+// @ts-check
+
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** @param {string[]} standardFiles @param {string} file */
+export function isManagedPath(standardFiles, file) {
+  return standardFiles.includes(file)
+}
+
+/** @param {string} root @param {string[]} standardFiles @returns {string[]} */
+export function customWorkflowFiles(root, standardFiles) {
+  const directory = join(root, '.github/workflows')
+  if (!existsSync(directory)) return []
+  return readdirSync(directory)
+    .filter((file) => file.endsWith('.yml') || file.endsWith('.yaml'))
+    .map((file) => `.github/workflows/${file}`)
+    .filter((file) => !isManagedPath(standardFiles, file))
+    .sort()
+}
+
+/** @param {string} root @param {Record<string, string>} config */
+export function overlayPolicy(root, config) {
+  const mode = config.sync_mode ?? 'overlay'
+  const custom = config.custom_workflows ?? 'preserve'
+  if (!['overlay', 'strict'].includes(mode)) throw new Error(`Unsupported sync_mode: ${mode}; use overlay or strict.`)
+  if (custom !== 'preserve') throw new Error(`Unsupported custom_workflows: ${custom}; custom workflows are always preserved.`)
+  return { mode, custom_workflows: custom }
+}

package/src/lib/profile.mjs

@@ -102,6 +102,32 @@ export function resolveProfile(root) {
   }
 }
 
+/**
+ * Recommend runners from detected workload cost. Slim is reserved for short
+ * metadata/security/PR jobs; native toolchains and browser/contract tests use
+ * the full runner.
+ * @param {string} root
+ */
+export function recommendRunners(root) {
+  const languages = detectLanguages(root)
+  const heavy = languages.some((language) => ['rust', 'python', 'solidity'].includes(language)) || hasBrowserProject(root)
+  return {
+    runner: heavy ? 'ubuntu-latest' : 'ubuntu-slim',
+    ci_runner: heavy ? 'ubuntu-latest' : 'ubuntu-slim',
+    test_runner: heavy ? 'ubuntu-latest' : 'ubuntu-slim',
+    unit_runner: heavy ? 'ubuntu-latest' : 'ubuntu-slim',
+    security_runner: 'ubuntu-slim',
+    codeql_runner: 'ubuntu-latest',
+    pr_runner: 'ubuntu-slim',
+    release_runner: 'ubuntu-slim',
+  }
+}
+
+/** @param {string} root */
+function hasBrowserProject(root) {
+  return ['playwright.config.ts', 'playwright.config.js', 'cypress.config.ts', 'cypress.config.js'].some((file) => existsSync(join(root, file)))
+}
+
 /** @param {string} root */
 function detectReleaseType(root) {
   if (existsSync(join(root, 'package.json'))) return 'node'

package/src/lib/release-hook.mjs

@@ -0,0 +1,40 @@
+// @ts-check
+
+import { createHash } from 'node:crypto'
+
+/** @typedef {'disabled'|'workflow-dispatch'|'release-event'|'unavailable'} HookDelivery */
+
+/**
+ * Select exactly one post-release delivery mechanism.
+ * @param {{ mode?: string, tokenPresent: boolean, releaseEventEnabled?: boolean }} input
+ * @returns {{ delivery: HookDelivery, reason: string }}
+ */
+export function selectHookDelivery(input) {
+  const mode = input.mode ?? 'auto'
+  if (mode === 'false' || mode === 'disabled') return { delivery: 'disabled', reason: 'Post-release hooks are disabled by configuration.' }
+  if (mode === 'workflow-dispatch' || (mode === 'auto' && input.tokenPresent)) {
+    return input.tokenPresent
+      ? { delivery: 'workflow-dispatch', reason: 'A PAT is available; use one explicit workflow dispatch.' }
+      : { delivery: 'unavailable', reason: 'workflow-dispatch requires a PAT.' }
+  }
+  if (mode === 'release-event' || (mode === 'auto' && input.releaseEventEnabled !== false)) {
+    return { delivery: 'release-event', reason: 'Use the published-release event; do not issue a fallback dispatch.' }
+  }
+  return { delivery: 'unavailable', reason: 'No supported post-release delivery mechanism is configured.' }
+}
+
+/** @param {string} repository @param {string} tag @returns {string} */
+export function releaseDeliveryKey(repository, tag) {
+  return createHash('sha256').update(`${repository}\0${tag}`).digest('hex').slice(0, 24)
+}
+
+/**
+ * A workflow dispatch is considered already delivered when a run exists for
+ * the release tag. Completed failures remain recorded so retries are explicit
+ * rather than accidentally duplicated by a second event path.
+ * @param {Array<{headBranch?: string, displayTitle?: string, status?: string}>} runs
+ * @param {string} tag
+ */
+export function hasDeliveredHook(runs, tag) {
+  return runs.some((run) => run.headBranch === tag || run.displayTitle?.includes(`release-tag=${tag}`))
+}

package/src/lib/release-policy.mjs

@@ -70,6 +70,81 @@ export function unexpectedReleasePaths(paths, allowed) {
     .filter((path) => !allowed.has(path))
 }
 
+/** @param {{ releasePleaseToken?: string, githubToken?: string }} input */
+export function selectReleaseCredential(input) {
+  if (input.releasePleaseToken) return { token: input.releasePleaseToken, source: 'release-please-token', autoMerge: true }
+  if (input.githubToken) return { token: input.githubToken, source: 'github-token', autoMerge: false }
+  return { token: '', source: 'missing', autoMerge: false }
+}
+
+/** @param {Array<{number?: number, title?: string, headRefName?: string}>} prs */
+export function selectGeneratedReleasePrs(prs) {
+  return prs.filter((pr) => /^chore\(main\): release /.test(pr.title ?? '') && String(pr.headRefName ?? '').startsWith('release-please--branches--main'))
+}
+
+/**
+ * Validate all generated release PR diffs before any merge is attempted.
+ * @param {Array<{number?: number, title?: string, headRefName?: string}>} prs
+ * @param {Map<number, string[]>} changedPathsByPr
+ * @param {Set<string>} allowed
+ */
+export function validateReleasePullRequests(prs, changedPathsByPr, allowed) {
+  const errors = []
+  const generated = selectGeneratedReleasePrs(prs)
+  if (!generated.length) errors.push('Release Please reported a PR, but no generated release PR was found.')
+  for (const pr of generated) {
+    const number = Number(pr.number)
+    const paths = changedPathsByPr.get(number)
+    if (!Array.isArray(paths) || !paths.length) {
+      errors.push(`Generated release PR #${number} has no changed files or its diff is malformed.`)
+      continue
+    }
+    const unexpected = unexpectedReleasePaths(paths, allowed)
+    if (unexpected.length) errors.push(`Generated release PR #${number} contains unexpected paths: ${unexpected.join(', ')}`)
+  }
+  return { valid: errors.length === 0, generated, errors }
+}
+
+/**
+ * Build a non-destructive release recovery plan from independent release
+ * metadata sources.
+ * @param {{ tags: string[], releases: Array<{tagName?: string}>, releasePrs: Array<{number?: number,title?: string}>, packageVersions: string[] }} input
+ */
+export function buildReleaseRecoveryPlan(input) {
+  const tags = [...new Set(input.tags.filter((tag) => /^v?\d+\.\d+\.\d+/.test(tag)))]
+  /** @type {string[]} */
+  const releaseTags = [...new Set(input.releases.map((release) => release.tagName).filter((tag) => typeof tag === 'string'))]
+  const tagSet = new Set(tags)
+  const releaseSet = new Set(releaseTags)
+  const missingGitHubReleases = tags.filter((tag) => !releaseSet.has(tag) && !releaseSet.has(tag.replace(/^v/, '')))
+  const orphanGitHubReleases = releaseTags.filter((tag) => !tagSet.has(tag) && !tagSet.has(tag.replace(/^v/, '')))
+  const latestTag = [...tags].sort(compareVersions).at(-1) ?? ''
+  const latestPackageVersion = [...input.packageVersions].sort(compareVersions).at(-1) ?? ''
+  return {
+    latestTag,
+    latestPackageVersion,
+    missingGitHubReleases,
+    orphanGitHubReleases,
+    pendingReleasePullRequests: input.releasePrs,
+    packageVersionMismatch: Boolean(latestTag && latestPackageVersion && normalizeVersion(latestTag) !== normalizeVersion(latestPackageVersion)),
+    actions: [
+      ...missingGitHubReleases.map((tag) => `create GitHub release metadata for ${tag}`),
+      ...(latestTag && latestPackageVersion && normalizeVersion(latestTag) !== normalizeVersion(latestPackageVersion) ? [`review package/tag mismatch (${latestPackageVersion} vs ${latestTag})`] : []),
+    ],
+  }
+}
+
+/** @param {string} value */
+function normalizeVersion(value) { return value.replace(/^v/, '').split('-')[0] }
+
+/** @param {string} a @param {string} b */
+function compareVersions(a, b) {
+  const left = normalizeVersion(a).split('.').map(Number)
+  const right = normalizeVersion(b).split('.').map(Number)
+  for (let index = 0; index < 3; index += 1) if ((left[index] ?? 0) !== (right[index] ?? 0)) return (left[index] ?? 0) - (right[index] ?? 0)
+  return a.localeCompare(b)
+}
+
 /**
  * Classify the relationship between main and staging. A fast-forward is safe
  * only when main is the ancestor of staging or staging is the ancestor of main