code-foundry 0.32.4 → 0.33.0

package/.github/workflows/validation.yml

@@ -0,0 +1,183 @@
+name: Code Foundry Validation
+
+on:
+  workflow_call:
+    inputs:
+      mode:
+        description: Validation tier (fast, audit, or release).
+        required: true
+        type: string
+      runtime-repository:
+        description: Repository containing the Code Foundry runtime.
+        required: false
+        type: string
+        default: 0xPlayerOne/code-foundry
+      runtime-ref:
+        description: Code Foundry runtime tag or ref.
+        required: false
+        type: string
+        default: v0.32.4
+      ci-runner:
+        description: Runner used by CI jobs.
+        required: false
+        type: string
+        default: ubuntu-latest
+      test-runner:
+        description: Runner used by non-unit test jobs.
+        required: false
+        type: string
+        default: ubuntu-latest
+      unit-runner:
+        description: Runner used by unit tests.
+        required: false
+        type: string
+        default: ubuntu-slim
+      security-runner:
+        description: Runner used by Security jobs.
+        required: false
+        type: string
+        default: ubuntu-slim
+      codeql-runner:
+        description: Runner used by CodeQL jobs.
+        required: false
+        type: string
+        default: ubuntu-latest
+      rust-shards:
+        description: JSON array of Rust scope sharding values. Use ["all"] for single-pass behavior.
+        required: false
+        type: string
+        default: '["all"]'
+      rust-threads:
+        description: Threads used for Rust extraction and analysis. Values above 1 opt into local parallelism.
+        required: false
+        type: string
+        default: '1'
+      rust-max-parallel:
+        description: Maximum Rust shard jobs allowed to run concurrently.
+        required: false
+        type: number
+        default: 1
+    secrets:
+      TURBO_TOKEN:
+        required: false
+      NEXTAUTH_SECRET:
+        required: false
+
+# The orchestrator keeps the union of permissions needed by the chain it calls
+# (CodeQL uploads require security-events: write). Nested reusable workflows
+# can only maintain or reduce permissions, never elevate them.
+permissions:
+  actions: read
+  contents: read
+  packages: read
+  security-events: write
+
+jobs:
+  ci:
+    name: CI
+    if: inputs.mode == 'fast' || inputs.mode == 'audit'
+    uses: ./.github/workflows/ci.yml
+    with:
+      runtime-repository: ${{ inputs.runtime-repository }}
+      runtime-ref: ${{ inputs.runtime-ref }}
+      runner: ${{ inputs.ci-runner }}
+    secrets:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      NEXTAUTH_SECRET: ${{ secrets.NEXTAUTH_SECRET }}
+
+  test:
+    name: Test
+    if: inputs.mode == 'fast' || inputs.mode == 'audit'
+    uses: ./.github/workflows/test.yml
+    with:
+      runtime-repository: ${{ inputs.runtime-repository }}
+      runtime-ref: ${{ inputs.runtime-ref }}
+      runner: ${{ inputs.test-runner }}
+      unit-runner: ${{ inputs.unit-runner }}
+      unit-only: ${{ inputs.mode == 'fast' }}
+    secrets:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+
+  security:
+    name: Security
+    if: inputs.mode == 'audit'
+    uses: ./.github/workflows/security.yml
+    with:
+      runtime-repository: ${{ inputs.runtime-repository }}
+      runtime-ref: ${{ inputs.runtime-ref }}
+      runner: ${{ inputs.security-runner }}
+
+  codeql:
+    name: CodeQL
+    if: inputs.mode == 'audit'
+    uses: ./.github/workflows/codeql.yml
+    with:
+      runtime-repository: ${{ inputs.runtime-repository }}
+      runtime-ref: ${{ inputs.runtime-ref }}
+      runner: ${{ inputs.codeql-runner }}
+      rust-shards: ${{ inputs.rust-shards }}
+      rust-threads: ${{ inputs.rust-threads }}
+      rust-max-parallel: ${{ inputs.rust-max-parallel }}
+
+  release-policy:
+    name: Release Policy
+    if: inputs.mode == 'release'
+    runs-on: ubuntu-slim
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+          filter: blob:none
+      - name: Checkout runtime
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          repository: ${{ inputs.runtime-repository }}
+          ref: ${{ inputs.runtime-ref }}
+          path: .github/.code-foundry
+          sparse-checkout: |
+            src/lib
+            src/runtime.mjs
+      - name: Install runtime
+        run: mv .github/.code-foundry "$RUNNER_TEMP/code-foundry"
+      - name: Validate generated release diff
+        env:
+          FOUNDRY_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          FOUNDRY_HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          FOUNDRY_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          FOUNDRY_REPOSITORY: ${{ github.repository }}
+        run: node "$RUNNER_TEMP/code-foundry/src/runtime.mjs" validation release_diff
+
+  # Aggregate check: "Validation / Gate" (caller job name + this job name).
+  # Always evaluates; only jobs required for the mode must have succeeded.
+  gate:
+    name: Gate
+    needs: [ci, test, security, codeql, release-policy]
+    if: always()
+    runs-on: ubuntu-slim
+    timeout-minutes: 10
+    env:
+      FOUNDRY_MODE: ${{ inputs.mode }}
+      FOUNDRY_CI: ${{ needs.ci.result }}
+      FOUNDRY_TEST: ${{ needs.test.result }}
+      FOUNDRY_SECURITY: ${{ needs.security.result }}
+      FOUNDRY_CODEQL: ${{ needs.codeql.result }}
+      FOUNDRY_RELEASE_POLICY: ${{ needs.release-policy.result }}
+    steps:
+      - name: Checkout runtime
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          repository: ${{ inputs.runtime-repository }}
+          ref: ${{ inputs.runtime-ref }}
+          path: .github/.code-foundry
+          sparse-checkout: |
+            src/lib
+            src/runtime.mjs
+      - name: Install runtime
+        run: mv .github/.code-foundry "$RUNNER_TEMP/code-foundry"
+      - name: Evaluate aggregate gate
+        run: node "$RUNNER_TEMP/code-foundry/src/runtime.mjs" validation gate

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

@@ -0,0 +1,82 @@
+name: Code Foundry
+
+on:
+  pull_request:
+    branches: [main, staging]
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
+  schedule:
+    - cron: '31 6 * * 1'
+  workflow_dispatch:
+
+# Default every caller job to no repository permissions. Individual jobs grant
+# only the scopes their own validation path consumes.
+permissions: {}
+
+# Superseded PR updates cancel the previous run; schedule and dispatch runs
+# are keyed by event so periodic audits and manual runs stay independent.
+concurrency:
+  group: code-foundry-validation-${{ github.event_name }}-${{ github.event.pull_request.head.repo.full_name || github.repository }}-${{ github.event.pull_request.head.ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  mode:
+    name: Mode
+    runs-on: ubuntu-slim
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    outputs:
+      mode: ${{ steps.classify.outputs.mode }}
+    steps:
+      - name: Checkout runtime
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+          repository: 0xPlayerOne/code-foundry
+          ref: ${{ github.sha }}
+          path: .github/.code-foundry
+          sparse-checkout: |
+            src/lib
+            src/runtime.mjs
+      - name: Install runtime
+        run: mv .github/.code-foundry "$RUNNER_TEMP/code-foundry"
+      - name: Classify validation mode
+        id: classify
+        env:
+          FOUNDRY_EVENT_NAME: ${{ github.event_name }}
+          FOUNDRY_BASE_REF: ${{ github.event.pull_request.base.ref }}
+          FOUNDRY_HEAD_REF: ${{ github.event.pull_request.head.ref }}
+        run: node "$RUNNER_TEMP/code-foundry/src/runtime.mjs" validation mode >> "$GITHUB_OUTPUT"
+
+  # The stable aggregate check name is the caller job name plus the
+  # orchestrator gate job name: "Validation / Gate". Keep both names fixed.
+  validation:
+    name: Validation
+    needs: mode
+    # Reusable workflows can only maintain or reduce the caller job's scopes.
+    # The audit tier needs security-events: write for CodeQL uploads.
+    permissions:
+      actions: read
+      contents: read
+      packages: read
+      security-events: write
+    uses: ./.github/workflows/validation.yml
+    with:
+      mode: ${{ needs.mode.outputs.mode }}
+      runtime-repository: 0xPlayerOne/code-foundry
+      runtime-ref: ${{ github.sha }}
+      ci-runner: ubuntu-latest
+      test-runner: ubuntu-latest
+      unit-runner: ubuntu-slim
+      security-runner: ubuntu-slim
+      codeql-runner: ubuntu-latest
+      rust-shards: '["all"]'
+      rust-threads: '1'
+      rust-max-parallel: 1
+    secrets:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      NEXTAUTH_SECRET: ${{ secrets.NEXTAUTH_SECRET }}

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.33.0](https://github.com/0xPlayerOne/code-foundry/compare/v0.32.4...v0.33.0) (2026-08-01)
+
+
+### Features
+
+* add tiered validation workflow ([#301](https://github.com/0xPlayerOne/code-foundry/issues/301)) ([dd3015e](https://github.com/0xPlayerOne/code-foundry/commit/dd3015ea22ab94b2ed3d55f6e900a04f3e968aeb))
+
+
+### Bug Fixes
+
+* preserve regex escape in test assertion ([#303](https://github.com/0xPlayerOne/code-foundry/issues/303)) ([0a3c56f](https://github.com/0xPlayerOne/code-foundry/commit/0a3c56f5318baa8002b1079687797702f2c06383))
+
 ## [0.32.4](https://github.com/0xPlayerOne/code-foundry/compare/v0.32.3...v0.32.4) (2026-08-01)
 
 

package/README.md

@@ -88,10 +88,13 @@ GitHub Code Quality or other paid GitHub features.
 See [Workflow and CI conventions](docs/WORKFLOWS.md) for triggers, required
 checks, runners, coverage, caching, and custom workflow extensions.
 
-The default contribution policy uses the `staging-release` workflow with
-rebase merges. Repositories can set `merge_strategy: squash` or
-`merge_strategy: merge` in `.github/code-foundry.yml` when their governance
-requires another merge convention.
+The contribution policy uses the `staging-release` workflow: feature PRs squash
+into `staging`, the promotion PR rebases into `main` (`merge_strategy: rebase`),
+and Release Please version PRs squash into `main` (`release_merge_strategy:
+squash`). Release automation never defaults to a merge method and never merges
+with `--admin`; `code-foundry doctor` and `code-foundry sync` fail closed on
+any other strategy. GitHub Stacks is not part of this topology and does not
+reduce the required workflow runs.
 
 ## Releases and publishing
 

package/docs/CONFIGURATION.md

@@ -48,7 +48,8 @@ repository manifests and source
 | `npm_publish` | `true` or `false` | Opt into npm publication |
 | `license` | `gpl-3.0-or-later`, `agpl-3.0-or-later`, `mit`, `preserve`, `none` | License policy; new repositories default to GPLv3 |
 | `git_workflow` | `staging-release` | Branch/release model; the standard model promotes `staging` into `main` |
-| `merge_strategy` | `rebase`, `squash`, `merge` | Preferred merge method for contribution and release PRs; defaults to `merge` |
+| `merge_strategy` | `rebase` | Promotion merge method for `staging` → `main`; the staging-release topology requires rebase |
+| `release_merge_strategy` | `squash` | Merge method for Release Please version PRs into `main`; release automation fails closed unless squash |
 | `runner` fields | GitHub runner names | Per-workflow runner policy |
 
 Supported features are `ci`, `codeql`, `security`, `test`, `draft-pr`,

package/docs/RELEASES.md

@@ -12,9 +12,13 @@ Keep commits Conventional Commit-shaped (`feat:`, `fix:`, `docs:`, `ci:`,
 `chore:`, and so on). Release Please uses them to select patch/minor/major
 versions and generate grouped changelog notes.
 
-The default `merge_strategy` is `merge`, matching promotion PRs from `staging` into `main`.
-Configure it to `squash` or `rebase` in `.github/code-foundry.yml` if a repository intentionally differs. The current
-supported `git_workflow` is `staging-release`.
+The merge audit pins one merge method per transition in this topology. Feature
+and fix branches land on `staging` with **squash** merges, the `staging` → `main`
+promotion PR merges with **rebase** (`merge_strategy: rebase`), and Release
+Please version PRs merge with **squash** (`release_merge_strategy: squash`).
+Release automation never defaults to a merge method and never merges with
+`--admin`: the release workflow fails closed unless `release_merge_strategy` is
+exactly `squash`. The current supported `git_workflow` is `staging-release`.
 
 The release workflow opens or updates a versioned PR after changes reach
 `main`. Merging that PR updates the changelog, creates the Git tag and GitHub
@@ -30,23 +34,27 @@ Set these values in `.github/code-foundry.yml`:
 ```yaml
 release_type: auto # auto, node, python, rust, simple, or none
 npm_publish: false # true only for an npm package
-merge_strategy: rebase # merge, squash, or rebase; used for promotion PRs
-release_merge_strategy: rebase # merge, squash, or rebase; used for Release Please PRs
+merge_strategy: rebase # required: staging -> main promotion PRs rebase
+release_merge_strategy: squash # required: Release Please version PRs squash only
 ```
 
 `merge_strategy` applies to promotion PRs (`staging` into `main`) and
-`release_merge_strategy` to Release Please version PRs; both default to
-`merge` when unset. Use **rebase** for promotion PRs and **squash** for
-Release Please PRs. Both keep `main` fully linear, which is what makes the
-post-release reconciliation possible: `staging` requires linear history, and
-any merge commit on `main` becomes an uncrossable barrier for `staging` (the
-linear-history rule rejects pushes whose new commits contain merge commits).
-Release Please itself also requires squash merges for its version PRs (rebase
-merges rewrite commit SHAs and break its merged-PR detection). With a linear
-`main`, the release workflow mirrors `staging` onto `main`'s tip after every
-release — a verified fast-forward when possible, otherwise a forced linear
-update, otherwise a single-parent synchronization commit — so `staging` is
-never left behind and never needs a manual rebase.
+`release_merge_strategy` to Release Please version PRs; feature PRs into
+`staging` use squash merges. The topology requires `merge_strategy: rebase`
+and `release_merge_strategy: squash`; `code-foundry doctor` and
+`code-foundry sync` reject any other value, and the release workflow fails
+closed instead of falling back to `merge`. Both keep `main` fully linear,
+which is what makes the post-release reconciliation possible: release-only
+main commits cannot be discarded because they are allowed metadata-only, and
+all non-metadata drift is rejected before mutation.
+
+Patch-equivalent divergence between `main` and `staging` is treated as aligned.
+When `staging` has pending commits that are not yet represented on `main`, the
+release workflow replays those staging-only commits in order onto a detached
+worktree rooted at `main`, and then updates `staging` with an exact
+`--force-with-lease` to prevent
+unintended branch rewrites. There is no unconditional mirror force-push and no
+fallback synchronization commit path.
 
 `auto` selects a supported manifest. Use `simple` with `version.txt` for a
 repository without a package manifest and `none` for a repository that should
@@ -78,6 +86,6 @@ the generated version pull request before using the token to merge it.
 
 1. Merge tested changes from `staging` into `main`.
 2. Review the generated Release Please PR and changelog.
-3. Merge the release PR with the repository.s configured `release_merge_strategy` (default `merge`, recommended `squash`).
+3. Merge the release PR with the repository's configured `release_merge_strategy` (**squash**; the release workflow fails closed on any other value).
 4. Confirm the GitHub Release and any package publication.
 5. Synchronize `staging` with the new `main` release commit.

package/docs/WORKFLOWS.md

@@ -2,16 +2,23 @@
 
 ## Standard triggers
 
-The default standard callers use:
+The canonical validation caller uses pull requests plus bounded audit entry
+points; it does not run the same suites again on branch pushes:
 
 ```yaml
-push:
-  branches: [main, staging]
 pull_request:
   branches: [main, staging]
+schedule:
+  - cron: '31 6 * * 1'
+workflow_dispatch:
 ```
 
-Draft PR automation may additionally listen to supported topic branches.
+Pull requests into `staging` run the fast tier, ordinary pull requests into
+`main` run the full audit tier, and exact Release Please pull requests into
+`main` run only release policy. Scheduled and manual runs select the audit
+tier. Draft PR automation separately listens to supported topic-branch pushes,
+promotion automation listens to `staging` pushes, and release automation
+listens to `main` pushes.
 Custom deployment, indexing, search, Slither, or other workflows are
 repository-owned extensions and should keep their own triggers and permissions.
 
@@ -31,6 +38,49 @@ Use concise job names such as `CI / Format`, `Test / Unit`, and
 `CodeQL / Analyze (Python)`. Required checks should match the jobs actually
 enabled for the repository profile.
 
+## Merge methods
+
+The merge audit pins one merge method per transition. `code-foundry doctor`
+and `code-foundry sync` fail closed on any other strategy, and the release
+workflow refuses to run unless its strategy is exactly `squash`.
+
+| Transition | Merge method | Enforcement |
+| --- | --- | --- |
+| Feature/fix PR into `staging` | Squash | Contribution policy; see `CONTRIBUTING.md` |
+| `staging` → `main` promotion PR | Rebase (`merge_strategy: rebase`) | `merge_strategy` must be `rebase`; merge commits are rejected |
+| Release Please version PR into `main` | Squash (`release_merge_strategy: squash`) | Release automation fails closed unless `squash`; never defaults to `merge`, never uses `--admin` |
+
+Keeping `main` linear — rebase promotions and squash release PRs — is what
+lets the post-release reconciliation fast-forward or replay `staging` safely.
+
+Protect `staging` with the aggregate `Validation / Gate`, squash-only pull
+requests, and a single GitHub Actions integration path. That path uses the
+GitHub Actions integration token by default, and optionally an SSH deploy key
+when `STAGING_DEPLOY_KEY` is configured. The deploy key is required only when
+a personal-repository ruleset for `staging` enforces a Deploy Key bypass for
+`release reconcile`; repositories without that bypass continue with tokenless
+checkout + GitHub API calls.
+
+When used, the optional `STAGING_DEPLOY_KEY` is written at runtime only for
+reconcile, used to set `GIT_SSH_COMMAND` and trusted host settings for the
+`release reconcile` transport, then scrubbed after the step.
+
+When absent, the job keeps `GH_TOKEN = github.token` and runs `gh auth setup-git`
+so repositories without a Deploy Key ruleset bypass still reconcile successfully.
+
+For this reconciliation path, maintainer PATs and administrator roles are not
+authorized bypasses; the job deliberately authenticates with `github.token`,
+not `CODE_FOUNDRY_TOKEN` or `RELEASE_PLEASE_TOKEN`.
+
+## GitHub Stacks
+
+GitHub Stacks (stacked pull requests) is not part of this topology and does
+not reduce required workflow runs. Every pull request in a stack still
+triggers its own validation run, and each branch keeps its own required
+checks; stacking never collapses or skips a required check in the tiered
+validation gate. Land changes through the standard `staging-release` flow
+instead.
+
 ## Language defaults
 
 - TypeScript/JavaScript: ESLint, Prettier, and Bun's native `bun test`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "0.32.4",
+  "version": "0.33.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/commands/doctor.mjs

@@ -6,6 +6,7 @@ import { spawnSync } from 'node:child_process'
 import { includesValue, readConfig } from '../lib/config.mjs'
 import { recommendRunners, resolveProfile } from '../lib/profile.mjs'
 import { doctorGithub } from '../lib/github-doctor.mjs'
+import { isGeneratedEventCaller } from './sync.mjs'
 
 /** @param {string} root @param {{ github?: boolean }} [options] */
 export function doctor(root, options = {}) {
@@ -68,15 +69,64 @@ export function doctor(root, options = {}) {
     }
   }
 
-  for (const workflow of ['ci', 'codeql', 'security', 'test', 'draft-pr', 'release-pr', 'release']) {
-    if (includesValue(config.features ?? 'all', workflow) && !existsSync(join(target, `.github/workflows/${workflow}.yml`))) error(`missing enabled workflow: ${workflow}.yml`)
+  const features = config.features ?? 'all'
+  const mergeStrategy = config.merge_strategy ?? 'rebase'
+  if (mergeStrategy !== 'rebase') {
+    error(`merge_strategy must be "rebase" for the staging-release promotion topology; got "${mergeStrategy}".`)
   }
-  console.log('Remote CI, Test, Security, CodeQL, and release runtimes are loaded by reusable workflow wrappers.')
+  const releaseMergeStrategy = config.release_merge_strategy ?? ''
+  if (includesValue(features, 'release') && releaseMergeStrategy !== 'squash') {
+    error(`release_merge_strategy must be "squash" for automated release merges; got "${releaseMergeStrategy || '(unset; release automation never defaults to merge)'}".`)
+  }
+  for (const workflow of ['validation', 'draft-pr', 'release-pr', 'release']) {
+    if (includesValue(features, workflow) && !existsSync(join(target, `.github/workflows/${workflow}.yml`))) error(`missing enabled workflow: ${workflow}.yml`)
+  }
+  const validationEnabled = includesValue(features, 'validation') || ['ci', 'test', 'security', 'codeql'].some((legacy) => includesValue(features, legacy))
+  const validationCaller = ['validation.yml', 'validation_self-ci.yml']
+    .map((file) => join(target, `.github/workflows/${file}`))
+    .find((file) => existsSync(file) && /pull_request:/.test(readFileSync(file, 'utf8')))
+  if (validationEnabled && !validationCaller) {
+    error('missing tiered validation caller; run code-foundry sync to adopt validation.yml')
+  } else if (validationCaller) {
+    const caller = readFileSync(validationCaller, 'utf8')
+    if (!/^  validation:\n    name: Validation/m.test(caller)) {
+      error('validation caller is missing the Validation job; the Validation / Gate aggregate check cannot form.')
+    }
+    if (!/uses:\s+(?:\.\/\.github\/workflows\/validation\.yml|\S+\/\.github\/workflows\/validation\.yml@)/.test(caller)) {
+      error('validation caller does not reference the validation orchestrator.')
+    }
+    const runtimeRef = caller.match(/^\s+runtime-ref:\s+(.+?)\s*$/m)?.[1]
+    const checkoutRef = caller.match(/^\s+ref:\s+(.+?)\s*$/m)?.[1]
+    if (!runtimeRef || !checkoutRef) {
+      error('validation caller is missing runtime ref wiring (mode checkout or orchestrator input).')
+    } else if (runtimeRef !== checkoutRef) {
+      error(`validation caller pins mismatched runtime refs (${runtimeRef} vs ${checkoutRef}).`)
+    } else if (runtimeRef !== '${{ github.sha }}' && !/^v\d+\.\d+\.\d+$/.test(runtimeRef)) {
+      warn(`validation caller runtime ref ${runtimeRef} is not a released tag; pin a vX.Y.Z tag.`)
+    }
+  }
+  const runtimeRepository = config.runtime_repository ?? '0xPlayerOne/code-foundry'
+  for (const stem of ['ci', 'test', 'security', 'codeql']) {
+    const legacy = join(target, `.github/workflows/${stem}.yml`)
+    if (existsSync(legacy) && isGeneratedEventCaller(readFileSync(legacy, 'utf8'), stem, runtimeRepository)) {
+      warn(`stale generated legacy caller ${stem}.yml still triggers canonical suites; run code-foundry sync to migrate to validation.yml.`)
+    }
+  }
+  console.log('Remote CI, Test, Security, CodeQL, and release runtimes are loaded by the tiered validation orchestrator.')
   if (options.github) {
     const github = doctorGithub(target)
+    /** @type {{ codeFoundryTokenPresent?: boolean, releasePleaseTokenPresent?: boolean, stagingDeployKeyPresent?: boolean }} */
+    const secrets = github.details.secrets ?? {}
     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}.`)
+    const codeFoundryToken = secrets.codeFoundryTokenPresent ? 'present' : 'absent'
+    const releasePleaseToken = secrets.releasePleaseTokenPresent ? 'present' : 'absent'
+    const stagingDeployKey = secrets.stagingDeployKeyPresent ? 'present' : 'absent'
+    console.log(`GitHub secrets: CODE_FOUNDRY_TOKEN=${codeFoundryToken}, RELEASE_PLEASE_TOKEN=${releasePleaseToken}, STAGING_DEPLOY_KEY=${stagingDeployKey}`)
+    if (!secrets.codeFoundryTokenPresent && !secrets.releasePleaseTokenPresent) {
+      warn('GitHub token routing fallback: PR creation will remain draft and requires manual ready-for-review to trigger validation.')
+    }
   }
   if (errors) throw new Error(`Repository doctor found ${errors} error(s).`)
   console.log('Repository doctor passed.')