code-foundry 1.4.1 → 1.5.1

package/.github/actions/codeql/action.yml

@@ -25,5 +25,9 @@ runs:
       uses: github/codeql-action/analyze@v4
       with:
         category: ${{ inputs.category }}
+        # Pin pull-request uploads to the contributor's head SHA/ref so a
+        # moving merge ref cannot race the required code-scanning context.
+        ref: ${{ github.event_name == 'pull_request' && format('refs/pull/{0}/head', github.event.pull_request.number) || github.ref }}
+        sha: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
         upload-database: false
         wait-for-processing: false

package/.github/dependabot.yml

@@ -29,8 +29,10 @@ updates:
         applies-to: version-updates
         patterns: ['*']
     ignore:
-      # TypeScript 7 cannot resolve node: builtins in this toolchain
-      # (verified); revisit when the TS/oxlint toolchain supports TS 7.
+      # TypeScript 7 (the native compiler) is supported by the oxlint/oxfmt
+      # toolchain; the tsconfig must use NodeNext or bundler resolution since
+      # legacy node10 resolution was removed. Held with 5.9 until each
+      # repository's tsconfig is verified on 7.
       - dependency-name: 'typescript'
         versions: ['>=7.0.0']
       # Held with TypeScript 5.9 above.

package/.github/workflows/cloudflare-deploy.yml

@@ -0,0 +1,98 @@
+name: Code Foundry Cloudflare Deploy
+
+on:
+  workflow_call:
+    inputs:
+      mode:
+        description: 'Deploy mode: preview (wrangler versions upload) or production (wrangler deploy).'
+        required: false
+        type: string
+        default: preview
+      working-directory:
+        description: 'Directory containing the wrangler configuration.'
+        required: false
+        type: string
+        default: '.'
+      runner:
+        required: false
+        type: string
+        default: ubuntu-latest
+      wrangler-version:
+        required: false
+        type: string
+        default: 'latest'
+      environment:
+        description: 'GitHub deployment environment. Defaults to Preview/Production based on the mode.'
+        required: false
+        type: string
+        default: ''
+    secrets:
+      CLOUDFLARE_API_TOKEN:
+        required: true
+      CLOUDFLARE_ACCOUNT_ID:
+        required: true
+
+permissions:
+  contents: read
+  deployments: write
+
+jobs:
+  deploy:
+    name: Cloudflare Deploy / ${{ inputs.mode }}
+    if: vars.CI_BILLING_PAUSED != 'true'
+    runs-on: ${{ inputs.runner }}
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Deploy to Cloudflare
+        id: deploy
+        working-directory: ${{ inputs.working-directory }}
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          WRANGLER_VERSION: ${{ inputs.wrangler-version }}
+          MODE: ${{ inputs.mode }}
+        run: |
+          set -euo pipefail
+          npx -y wrangler@"$WRANGLER_VERSION" --version
+          if [ "$MODE" = "production" ]; then
+            npx -y wrangler@"$WRANGLER_VERSION" deploy 2>&1 | tee deploy-output.txt
+          elif [ "$MODE" = "preview" ]; then
+            npx -y wrangler@"$WRANGLER_VERSION" versions upload --message "preview ${GITHUB_SHA::7}" 2>&1 | tee deploy-output.txt
+          else
+            echo "Unsupported mode: $MODE (use preview or production)" >&2
+            exit 1
+          fi
+          # Prefer version preview URLs; fall back to the first workers.dev URL.
+          url=$(grep -Eo 'https://[a-zA-Z0-9][a-zA-Z0-9.-]*\.workers\.dev' deploy-output.txt | tail -1 || true)
+          echo "url=$url" >> "$GITHUB_OUTPUT"
+
+      - name: Record GitHub deployment
+        env:
+          GH_TOKEN: ${{ github.token }}
+          MODE: ${{ inputs.mode }}
+          ENVIRONMENT_OVERRIDE: ${{ inputs.environment }}
+          DEPLOY_URL: ${{ steps.deploy.outputs.url }}
+        run: |
+          set -euo pipefail
+          if [ "$MODE" != "production" ] && [ "$MODE" != "preview" ]; then
+            echo "Unsupported mode: $MODE" >&2
+            exit 1
+          fi
+          environment="${ENVIRONMENT_OVERRIDE:-$([ "$MODE" = "production" ] && echo Production || echo Preview)}"
+          body=$(jq -n \
+            --arg ref "$GITHUB_SHA" \
+            --arg environment "$environment" \
+            --argjson production "$([ "$MODE" = "production" ] && echo true || echo false)" \
+            '{ref: $ref, environment: $environment, auto_merge: false, production_environment: $production, required_contexts: []}')
+          deployment=$(gh api "repos/$GITHUB_REPOSITORY/deployments" --input - <<< "$body" --jq .id)
+          status_args=(-f state=success -f description="Cloudflare $MODE deploy (${GITHUB_SHA::7})")
+          if [ -n "$DEPLOY_URL" ]; then
+            status_args+=(-f environment_url="$DEPLOY_URL" -f log_url="$DEPLOY_URL")
+          fi
+          gh api -X POST "repos/$GITHUB_REPOSITORY/deployments/$deployment/statuses" "${status_args[@]}" --jq .state
+          echo "Recorded $environment deployment for ${GITHUB_SHA::7}"

package/.github/workflows/codeql.yml

@@ -285,6 +285,10 @@ jobs:
         uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4
         with:
           category: /language:rust/${{ steps.scope.outputs.scope_id }}
+          # Keep uploads attached to the PR head rather than the mutable
+          # merge ref used by GitHub's pull_request event.
+          ref: ${{ github.event_name == 'pull_request' && format('refs/pull/{0}/head', github.event.pull_request.number) || github.ref }}
+          sha: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
           upload-database: false
           wait-for-processing: false
       - name: Not applicable

package/.github/workflows/release.yml

@@ -89,17 +89,21 @@ jobs:
           let releaseType = config.release_type || 'auto'
           let npmPublish = config.npm_publish || 'false'
           // The merge audit topology requires rebase for Release Please version
-          // pull requests into main, matching the linear-history ruleset.
-          // Release automation never defaults to a merge method: an unset or
-          // non-rebase release_merge_strategy fails the release job before any
-          // pull request is created or merged.
+          // pull requests into main, matching the linear-history ruleset. The
+          // direct topology may also opt into squash: a single-commit release
+          // PR squashes to the identical tree and release-please recommends
+          // squash. Release automation never defaults to a merge method: an
+          // unset or unsupported release_merge_strategy fails the release job
+          // before any pull request is created or merged.
+          const gitWorkflow = String(config.git_workflow || 'direct').trim().toLowerCase()
           const releaseMergeStrategy = String(config.release_merge_strategy || '').trim().toLowerCase()
           if (releaseType === 'auto') {
             releaseType = fs.existsSync('package.json') ? 'node' : fs.existsSync('pyproject.toml') ? 'python' : fs.existsSync('Cargo.toml') ? 'rust' : fs.existsSync('version.txt') ? 'simple' : 'none'
           }
           if (!['node', 'python', 'rust', 'simple', 'none'].includes(releaseType)) throw new Error(`Unsupported release_type: ${releaseType}`)
-          if (releaseMergeStrategy !== 'rebase') {
-            throw new Error(`release_merge_strategy must be "rebase" for automated release merges; got ${releaseMergeStrategy || '(unset; release automation never defaults to merge)'}`)
+          const allowedStrategies = gitWorkflow === 'staging-release' ? ['rebase'] : ['rebase', 'squash']
+          if (!allowedStrategies.includes(releaseMergeStrategy)) {
+            throw new Error(`release_merge_strategy must be "rebase"${gitWorkflow === 'staging-release' ? '' : ' or "squash" (direct topology)'} for automated release merges; got ${releaseMergeStrategy || '(unset; release automation never defaults to merge)'}`)
           }
           if (releaseType === 'none' || !fs.existsSync('package.json')) npmPublish = 'false'
           let legacyReleaseType = ''

package/.oxlintrc.json

@@ -1,5 +1,5 @@
 {
   "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "categories": { "correctness": "error" },
+  "categories": { "correctness": "error", "suspicious": "warn" },
   "ignorePatterns": ["node_modules/**"]
 }

package/AGENTS.md

@@ -77,6 +77,21 @@ This repository uses the `staging-release` workflow: topic branches **squash** i
 
 Merge only with the repository's canonical method. Never merge with `--admin`, never default or auto-select a merge method, and never use a method the branch ruleset does not allow. When in doubt, prefer the merge button's configured method and verify the ruleset after merging. Check `.github/CONTRIBUTING.md` for the complete flow and merge table.
 
+### Branch and commit policy
+
+Branch rulesets enforce deletions, force-pushes, required status checks, pull
+requests, conversation resolution, and linear history where the repository's
+plan supports them. Mirror those rules even where the plan cannot enforce
+them:
+
+- Branch from the default branch using
+  `feat/*`, `fix/*`, `chore/*`, `refactor/*`, `docs/*`, or `test/*` names.
+- Never push directly to protected branches; open a pull request.
+- Use Conventional Commit subjects (`feat:`, `fix:`, `chore:`, …); Release
+  Please depends on them to version releases.
+- Keep pull requests focused; merge with the canonical method only after
+  required checks pass.
+
 ## Toolchain and dependencies
 
 - Follow `toolchain: auto` in `.github/code-foundry.yml`; use native tools by
@@ -112,7 +127,7 @@ Run focused tests first, then the complete applicable set for release, security,
 
 At minimum:
 
-- TypeScript/JavaScript: Oxfmt formatting, Oxlint linting, type-check, build, and Bun's native test runner for unit/integration tests; use the project's native browser runner for E2E tests. Repositories still on Prettier/ESLint keep working through the runtime's fallback detection until they migrate.
+- TypeScript/JavaScript: Oxfmt formatting, Oxlint linting, type-check, build, and Bun's native test runner for unit/integration tests; use the project's native browser runner for E2E tests. Repositories using a different linter or formatter keep full control through their own `lint`/`format` scripts, which the runtime honors.
 - Do not add Vitest. Preserve specialized native runners such as Matchstick for The Graph and Hardhat for smart contracts.
 - Rust: default rustfmt, Clippy with warnings treated as errors, check, unit/integration tests, and dependency audit
 - Python: Ruff formatting and linting, compile or type checks, pytest, coverage, and dependency audit

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.5.1](https://github.com/0xPlayerOne/code-foundry/compare/v1.5.0...v1.5.1) (2026-09-08)
+
+
+### Bug Fixes
+
+* sync-caller-runtime-pin ([#484](https://github.com/0xPlayerOne/code-foundry/issues/484)) ([e1a216a](https://github.com/0xPlayerOne/code-foundry/commit/e1a216a9dcebd040ef0eacdb20791f360a921908))
+
+## [1.5.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.4.1...v1.5.0) (2026-09-07)
+
+
+### Features
+
+* **release:** squash release merges, Cloudflare deploy workflow, tooling neutrality ([6a847eb](https://github.com/0xPlayerOne/code-foundry/commit/6a847eb0a3f78dbd343b7b189f32543d621b4b8a))
+
 ## [1.4.1](https://github.com/0xPlayerOne/code-foundry/compare/v1.4.0...v1.4.1) (2026-09-07)
 
 

package/README.md

@@ -74,7 +74,8 @@ The standard workflow triggers are:
 
 Jobs are language-aware and skip irrelevant setup while remaining visible as
 successful required checks. TypeScript uses Oxlint, Oxfmt, and Bun's native
-test runner (Prettier/ESLint setups keep working through fallback detection).
+test runner (repositories using another linter or formatter keep full control
+through their own `lint`/`format` scripts, which the runtime honors).
 Rust uses `rustfmt`, Clippy with warnings as errors, and native
 Cargo tests. Python uses Ruff, uv/pip-compatible setup, and native Python
 tests. Solidity projects retain their native toolchain and test runner.
@@ -90,15 +91,16 @@ See [Workflow and CI conventions](docs/WORKFLOWS.md) for triggers, required
 checks, runners, coverage, caching, and custom workflow extensions.
 
 The contribution policy defaults to the `direct` workflow: feature PRs squash
-into `main`, and Release Please version PRs rebase into `main`
-(`release_merge_strategy: rebase`). Repositories with a preview/staging
-environment opt into `git_workflow: staging-release`, where feature PRs squash
-into `staging`, the promotion PR rebases into `main` (`merge_strategy:
-rebase`), and Release Please version PRs rebase into `main`. 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.
+into `main`, and Release Please version PRs use the configured
+`release_merge_strategy` (rebase by default, or squash when opted in).
+Repositories with a preview/staging environment opt into
+`git_workflow: staging-release`, where feature PRs squash into `staging`, the
+promotion PR rebases into `main` (`merge_strategy: rebase`), and Release Please
+version PRs rebase into `main`. Release automation never defaults to a merge
+method and never merges with `--admin`; `code-foundry doctor` and
+`code-foundry sync` fail closed on any strategy outside the selected topology.
+GitHub Stacks is not part of this topology and does not reduce the required
+workflow runs.
 
 ## Releases and publishing
 

package/docs/CONFIGURATION.md

@@ -50,7 +50,7 @@ repository manifests and source
 | `license`                  | `gpl-3.0-or-later`, `agpl-3.0-or-later`, `apache-2.0`, `mit`, `preserve`, `none` | License policy; new repositories default to GPLv3                                                                   |
 | `git_workflow`             | `direct` (default), `staging-release`                                            | Branch/release model; `direct` opens feature branches into `main`, `staging-release` promotes `staging` into `main` |
 | `merge_strategy`           | `rebase`                                                                         | Promotion merge method for `staging` → `main`; only enforced by the `staging-release` topology                      |
-| `release_merge_strategy`   | `rebase`                                                                         | Merge method for Release Please version PRs into `main`; release automation fails closed unless rebase              |
+| `release_merge_strategy`   | `rebase`, `squash` (direct topology only)                                        | Merge method for Release Please version PRs into `main`; release automation fails closed on anything else           |
 | `runner` fields            | GitHub runner names                                                              | Per-workflow runner policy                                                                                          |
 
 Supported features are `ci`, `codeql`, `security`, `test`, `draft-pr`,
@@ -77,8 +77,9 @@ present.
 - `direct` (default): feature branches open pull requests directly into
   `main`. Validation and security scans run on every PR. No `staging` branch
   exists, no promotion caller is generated, and `merge_strategy` is not
-  enforced. Dependabot updates target `main`. This is the right choice when a
-  repository has no preview or staging environment.
+  enforced. Release Please version PRs use `release_merge_strategy` (rebase by
+  default; squash is also allowed). Dependabot updates target `main`. This is
+  the right choice when a repository has no preview or staging environment.
 - `staging-release` (opt-in): feature branches squash into `staging`, a
   promotion PR rebases validated changes into `main` (`merge_strategy:
 rebase`), and Release Please version PRs rebase into `main`
@@ -115,3 +116,14 @@ Each scoped shard must contain tracked Rust source. Code Foundry rejects
 absolute paths, parent traversal, duplicates, empty scopes, and more than eight
 shards. Do not split a single crate by arbitrary non-Rust directories: use
 `["all"]` when complete, non-overlapping source scopes are not available.
+
+## Cloudflare Workers deployments
+
+Repositories that deploy to Cloudflare Workers can opt into GitHub-native
+deployments (Preview/Production environments with deployment statuses, like
+Vercel's integration) by adding a small caller for the runtime's reusable
+`cloudflare-deploy.yml` workflow. The workflow runs `wrangler versions upload`
+for pull-request previews and `wrangler deploy` for production, records a
+GitHub deployment plus status with the workers.dev URL, and respects
+`CI_BILLING_PAUSED`. It requires the `CLOUDFLARE_API_TOKEN` and
+`CLOUDFLARE_ACCOUNT_ID` secrets in the consumer repository.

package/docs/RELEASES.md

@@ -24,10 +24,11 @@ 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 **rebase**
 (`release_merge_strategy: rebase`). In the `direct` topology, feature and fix
-branches squash straight into `main` and only Release Please version PRs merge
-with **rebase**; `merge_strategy` is not enforced. Release automation never
-defaults to a merge method and never merges with `--admin`: the release
-workflow fails closed unless `release_merge_strategy` is exactly `rebase`.
+branches squash straight into `main` and Release Please version PRs use the
+configured `release_merge_strategy` (**rebase** by default, or **squash** when
+opted in). `merge_strategy` is not enforced. Release automation never defaults
+to a merge method and never merges with `--admin`: `staging-release` accepts
+only rebase for release PRs, while `direct` accepts rebase or squash.
 
 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
@@ -45,21 +46,21 @@ release_type: auto # auto, node, python, rust, simple, or none
 npm_publish: false # true only for an npm package
 git_workflow: direct # direct (default) or staging-release
 merge_strategy: rebase # staging-release only: staging -> main promotion PRs rebase
-release_merge_strategy: rebase # required: Release Please version PRs rebase only
+release_merge_strategy: rebase # required; direct also allows squash
 ```
 
 `git_workflow: staging-release` is opt-in; without it, repositories use the
 `direct` flow and no promotion PR exists. When the staging-release topology is
 selected, `merge_strategy` applies to promotion PRs (`staging` into `main`)
 and `release_merge_strategy` to Release Please version PRs; feature PRs into
-`staging` use squash merges. `code-foundry doctor` and `code-foundry sync`
-reject any non-`rebase` `merge_strategy` only when `staging-release` is
-configured, and always reject a non-`rebase` `release_merge_strategy`; 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. The final branch trees are inspected before mutation; validated
-main-only changes are inherited by `staging`, while unpromoted staging work is
-replayed on top of `main`.
+`staging` use squash merges. `code-foundry doctor`, `code-foundry sync`, and
+the release workflow reject any non-`rebase` `merge_strategy` or release
+strategy in `staging-release`; `direct` accepts `rebase` or `squash` for
+release PRs and never falls back to `merge`. Both keep `main` fully linear,
+which is what makes the post-release reconciliation possible. The final
+branch trees are inspected before mutation; validated main-only changes are
+inherited by `staging`, while unpromoted staging work is replayed on top of
+`main`.
 
 Promotion never opens a pull request directly from a divergent `staging`
 history. The workflow creates or refreshes a deterministic promotion branch
@@ -135,6 +136,6 @@ already passed).
 
 1. Merge tested changes into `main` (direct: feature PRs; staging-release: promote `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` (**rebase**; the release workflow fails closed on any other value).
+3. Merge the release PR with the repository's configured `release_merge_strategy` (**rebase** by default; **squash** is also valid for direct topology).
 4. Confirm the GitHub Release and any package publication.
 5. staging-release only: synchronize `staging` with the new `main` release commit.

package/docs/WORKFLOWS.md

@@ -100,15 +100,17 @@ succeeds.
 ## 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 `rebase`.
-
-| Transition                                                 | Merge method                              | Enforcement                                                                                                                                                                |
-| ---------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Feature/fix PR into `main` (direct topology)               | Squash                                    | Contribution policy; see `CONTRIBUTING.md`                                                                                                                                 |
-| Feature/fix PR into `staging` (staging-release topology)   | Squash                                    | Contribution policy; see `CONTRIBUTING.md`                                                                                                                                 |
-| `staging` → `main` promotion PR (staging-release topology) | Rebase (`merge_strategy: rebase`)         | Code Foundry creates a one-commit head with `main` as its parent and the exact validated `staging` tree; `merge_strategy` must be `rebase`, and merge commits are rejected |
-| Release Please version PR into `main`                      | Rebase (`release_merge_strategy: rebase`) | Release automation fails closed unless `rebase`; never defaults to `merge`, never uses `--admin`                                                                           |
+and `code-foundry sync` validate release strategy against the repository
+topology. Staging-release release PRs require `rebase`; direct release PRs
+allow `rebase` or `squash`. The release workflow fails closed on any other
+strategy and never falls back to `merge`.
+
+| Transition                                                 | Merge method                                                              | Enforcement                                                                                                                                                                |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Feature/fix PR into `main` (direct topology)               | Squash                                                                    | Contribution policy; see `CONTRIBUTING.md`                                                                                                                                 |
+| Feature/fix PR into `staging` (staging-release topology)   | Squash                                                                    | Contribution policy; see `CONTRIBUTING.md`                                                                                                                                 |
+| `staging` → `main` promotion PR (staging-release topology) | Rebase (`merge_strategy: rebase`)                                         | Code Foundry creates a one-commit head with `main` as its parent and the exact validated `staging` tree; `merge_strategy` must be `rebase`, and merge commits are rejected |
+| Release Please version PR into `main`                      | Configured (`release_merge_strategy`: rebase default; squash direct only) | Release automation fails closed on unsupported topology/strategy; never defaults to `merge`, never uses `--admin`                                                          |
 
 The promotion rows above apply only to `staging-release`; `direct`
 repositories never generate a promotion caller and `merge_strategy` is not
@@ -123,14 +125,18 @@ additional required checks after earlier ones have passed (for example
 merge policy-blocked. The mergeability poll is bounded and fails closed on
 conflicts or timeout; releases without an automation token remain manual.
 
-Keeping `main` linear — rebase promotions and rebase release PRs — is what
-lets the post-release reconciliation fast-forward or replay `staging` safely
-in the `staging-release` topology. `direct` repositories have no reconciliation
-step: releases merge straight into `main` with `release_merge_strategy: rebase`.
-
-Protect `main` with the aggregate `Validation / Gate` and squash-only pull
-requests. In the `staging-release` topology, protect `staging` the same way
-with a single GitHub Actions integration path. That path uses the
+Keeping `main` linear — rebase promotions and release PRs in the
+`staging-release` topology, or a single-commit rebase/squash release PR in the
+`direct` topology — is what lets the post-release reconciliation fast-forward
+or replay `staging` safely. `direct` repositories have no reconciliation step:
+releases merge straight into `main` with the configured
+`release_merge_strategy`.
+
+Protect `main` with the aggregate `Validation / Gate`. Require squash for
+feature/fix pull requests and permit the configured Release Please method:
+rebase in `staging-release`, or rebase/squash in `direct`. In the
+`staging-release` topology, protect `staging` the same way with 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "A fast, language-aware repository factory for agent-ready workflows, testing, security, and release automation.",
   "homepage": "https://github.com/0xPlayerOne/code-foundry#readme",
   "bugs": {

package/src/commands/doctor.mjs

@@ -122,9 +122,14 @@ export function doctor(root, options = {}) {
     )
   }
   const releaseMergeStrategy = config.release_merge_strategy ?? ''
-  if (includesValue(features, 'release') && releaseMergeStrategy !== 'rebase') {
+  const allowedReleaseStrategies =
+    workflow === 'staging-release' ? ['rebase'] : ['rebase', 'squash']
+  if (
+    includesValue(features, 'release') &&
+    !allowedReleaseStrategies.includes(releaseMergeStrategy)
+  ) {
     error(
-      `release_merge_strategy must be "rebase" for automated release merges; got "${releaseMergeStrategy || '(unset; release automation never defaults to merge)'}".`
+      `release_merge_strategy must be "rebase"${workflow === 'staging-release' ? '' : ' or "squash" (direct topology)'} for automated release merges; got "${releaseMergeStrategy || '(unset; release automation never defaults to merge)'}".`
     )
   }
   for (const name of ['validation', 'draft-pr', 'release-pr', 'release']) {

package/src/commands/fleet.mjs

@@ -4,7 +4,7 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } fro
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { spawnSync } from 'node:child_process'
-import { syncRepository } from './sync.mjs'
+import { readPackageVersion, syncRepository } from './sync.mjs'
 
 /** @typedef {{ path: string, repository: string, runtimeRef: string, dirty: boolean, configured: boolean, gitWorkflow: string }} FleetRepository */
 
@@ -32,6 +32,13 @@ export function discoverRepositories(root) {
 
 /** @param {string} root @param {string} source @param {{ createPr?: boolean, dryRun?: boolean, force?: boolean, version: string, exclude?: string[] }} options */
 export function upgradeFleet(root, source, options) {
+  const sourceVersion = `v${readPackageVersion(source)}`
+  const version = options.version ?? sourceVersion
+  if (options.version && options.version !== sourceVersion) {
+    throw new Error(
+      `fleet upgrade target ${options.version} does not match the runtime source checkout (${sourceVersion}); refresh the code-foundry checkout to ${options.version} before upgrading so the rendered callers and the declared runtime agree.`
+    )
+  }
   const repositories = discoverRepositories(root)
   const report = []
   for (const repository of repositories) {
@@ -80,7 +87,7 @@ export function upgradeFleet(root, source, options) {
       })
       continue
     }
-    report.push(upgradeRepository(repository, source, options.version))
+    report.push(upgradeRepository(repository, source, version))
   }
   console.log(JSON.stringify(report, null, 2))
   return report
@@ -121,7 +128,12 @@ function upgradeRepository(repository, source, version) {
         status: 'skipped',
         reason: add.stderr.trim() || 'unable to create isolated worktree',
       }
-    const result = syncRepository({ target: temporary, source, force: false })
+    const result = syncRepository({
+      target: temporary,
+      source,
+      force: false,
+      runtimeRef: version,
+    })
     const configFile = join(temporary, '.github/code-foundry.yml')
     if (existsSync(configFile)) {
       const current = readFileSync(configFile, 'utf8')

package/src/commands/sync.mjs

@@ -96,7 +96,7 @@ const legacyFiles = [
   '.github/licenses/AGPL-3.0-or-later.txt',
 ]
 
-/** @typedef {{ target: string, source: string, dryRun?: boolean, force?: boolean, init?: boolean }} SyncOptions */
+/** @typedef {{ target: string, source: string, dryRun?: boolean, force?: boolean, init?: boolean, runtimeRef?: string }} SyncOptions */
 
 /** @param {SyncOptions} options */
 export function syncRepository(options) {
@@ -137,7 +137,11 @@ export function syncRepository(options) {
   const features = configured(config.features, 'all')
   const runtimeRepository = configured(config.runtime_repository, '0xPlayerOne/code-foundry')
   const sourceRuntimeRef = `v${readPackageVersion(source)}`
-  let runtimeRef = configured(config.runtime_ref, sourceRuntimeRef)
+  // An explicit runtime ref (fleet upgrade) is authoritative: the rendered
+  // callers and the config pin must agree with it, otherwise an upgrade would
+  // declare one runtime while shipping another.
+  const targetRuntimeRef = options.runtimeRef ?? sourceRuntimeRef
+  let runtimeRef = options.runtimeRef ?? configured(config.runtime_ref, sourceRuntimeRef)
   const toolchain = configured(config.toolchain, 'auto')
   const overlays = overlayPolicy(target, config)
   const rustCodeql = validateRustCodeqlConfig(config)
@@ -161,23 +165,33 @@ export function syncRepository(options) {
     )
   }
   const releaseMergeStrategy = configured(config.release_merge_strategy, '')
-  if (includesValue(features, 'release') && releaseMergeStrategy !== 'rebase') {
-    throw new Error(
-      `Unsupported release_merge_strategy: ${releaseMergeStrategy || '(unset)'}; release automation requires rebase for Release Please version pull requests and never defaults to merge.`
-    )
+  if (includesValue(features, 'release')) {
+    // Staging-release reconciliations depend on rebase promotions and rebase
+    // release commits; the direct topology has no reconciliation step, so it
+    // may also squash Release Please version PRs (a single-commit release PR
+    // squashes to the identical tree, and release-please recommends squash).
+    const allowedReleaseStrategies =
+      workflow === 'staging-release' ? ['rebase'] : ['rebase', 'squash']
+    if (!allowedReleaseStrategies.includes(releaseMergeStrategy)) {
+      throw new Error(
+        `Unsupported release_merge_strategy: ${releaseMergeStrategy || '(unset)'}; release automation requires rebase (or squash in the direct topology) for Release Please version pull requests and never defaults to merge.`
+      )
+    }
   }
   const changed = []
 
   // Keep normal semver pins current during sync while preserving intentional
-  // refs such as `main`, `staging`, or a custom immutable SHA.
+  // refs such as `main`, `staging`, or a custom immutable SHA. An explicit
+  // runtime ref (fleet upgrade) is authoritative and overrides even those so
+  // the rendered callers and the config pin land on the same runtime.
   if (
     existingConfig.runtime_ref &&
-    /^v\d+\.\d+\.\d+$/.test(existingConfig.runtime_ref) &&
-    existingConfig.runtime_ref !== sourceRuntimeRef
+    existingConfig.runtime_ref !== targetRuntimeRef &&
+    (options.runtimeRef !== undefined || /^v\d+\.\d+\.\d+$/.test(existingConfig.runtime_ref))
   ) {
-    runtimeRef = sourceRuntimeRef
+    runtimeRef = targetRuntimeRef
     const current = readFileSync(configPath, 'utf8')
-    const updated = current.replace(/^runtime_ref:\s*.*$/m, `runtime_ref: ${sourceRuntimeRef}`)
+    const updated = current.replace(/^runtime_ref:\s*.*$/m, `runtime_ref: ${targetRuntimeRef}`)
     if (updated !== current) {
       changed.push('.github/code-foundry.yml')
       writeOrReport(configPath, updated, dryRun)
@@ -643,7 +657,7 @@ const DIRECT_DOC_REPLACEMENTS = {
     ],
     [
       'This repository uses the `staging-release` workflow: topic branches **squash** into `staging`, a promotion PR **rebases** validated changes into `main` (`merge_strategy: rebase`), and the Release Please version PR **rebases** into `main` (`release_merge_strategy: rebase`). Feature PRs land on `staging` with squash merges; promotion and release PRs land on `main` with rebase merges. Re-align `staging` with `main` after a release when needed.',
-      'This repository uses the `direct` workflow: topic branches **squash** directly into `main`, and the Release Please version PR **rebases** into `main` (`release_merge_strategy: rebase`). Feature PRs land on `main` with squash merges; release PRs land on `main` with rebase merges. No integration branch exists; all pull requests target `main`.',
+      'This repository uses the `direct` workflow: topic branches **squash** directly into `main`, and the Release Please version PR lands on `main` with the configured `release_merge_strategy` (rebase by default, or squash when opted in). Feature PRs land on `main` with squash merges. No integration branch exists; all pull requests target `main`.',
     ],
   ],
   '.github/CONTRIBUTING.md': [
@@ -661,7 +675,7 @@ const DIRECT_DOC_REPLACEMENTS = {
     ],
     [
       'The Git workflow is `staging-release`: topic branches **squash** into `staging`, a promotion PR **rebases** validated changes into `main` (`merge_strategy: rebase`), and the Release Please version PR **rebases** into `main` (`release_merge_strategy: rebase`). 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 merge strategy. Re-align `staging` with `main` after a release when needed.',
-      'The Git workflow is `direct`: topic branches **squash** directly into `main`, and the Release Please version PR **rebases** into `main` (`release_merge_strategy: rebase`). 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 release merge strategy. Feature branches never touch `staging`; repositories with a preview/staging environment opt into `git_workflow: staging-release` explicitly.',
+      'The Git workflow is `direct`: topic branches **squash** directly into `main`, and the Release Please version PR lands on `main` with the configured `release_merge_strategy` (rebase by default, or squash when opted in). 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 release merge strategy. Feature branches never touch `staging`; repositories with a preview/staging environment opt into `git_workflow: staging-release` explicitly.',
     ],
     [
       'git switch staging\ngit pull --ff-only origin staging',
@@ -687,7 +701,7 @@ const DIRECT_DOC_REPLACEMENTS = {
     ],
     [
       '| Change                       | Target    | Merge method                                    | Merge gate                                                |\n| ---------------------------- | --------- | ----------------------------------------------- | --------------------------------------------------------- |\n| Working branch               | `staging` | Squash                                          | All applicable required checks pass                       |\n| `staging` → `main` promotion | `main`    | Rebase (`merge_strategy`)                       | Current staging checks, release review, and rollout notes |\n| Release Please version PR    | `main`    | Rebase (`release_merge_strategy`, fails closed) | Validation gate and release policy pass                   |\n',
-      '| Change | Target | Merge method | Merge gate |\n|----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Working branch | `main` | Squash | All applicable required checks pass |\n| Release Please version PR | `main` | Rebase (`release_merge_strategy`, fails closed) | Validation gate and release policy pass |',
+      '| Change | Target | Merge method | Merge gate |\n|----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Working branch | `main` | Squash | All applicable required checks pass |\n| Release Please version PR | `main` | Configured `release_merge_strategy` (rebase default, or squash in the direct topology) | Validation gate and release policy pass |',
     ],
     ['1. Create a focused branch from `staging`.', '1. Create a focused branch from `main`.'],
   ],
@@ -821,6 +835,103 @@ function mergeGitignore(baseline, existing) {
     : baseline
 }
 
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isJsonObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** @param {string} source @returns {string} */
+function stripJsonComments(source) {
+  const output = []
+  let inString = false
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index]
+    const next = source[index + 1]
+    if (inString) {
+      output.push(char)
+      if (char === '\\' && next !== undefined) {
+        output.push(next)
+        index += 1
+      } else if (char === '"') {
+        inString = false
+      }
+      continue
+    }
+    if (char === '"') {
+      inString = true
+      output.push(char)
+      continue
+    }
+    if (char === '/' && next === '/') {
+      output.push(' ', ' ')
+      index += 2
+      while (index < source.length && source[index] !== '\n' && source[index] !== '\r') {
+        output.push(' ')
+        index += 1
+      }
+      index -= 1
+      continue
+    }
+    if (char === '/' && next === '*') {
+      output.push(' ', ' ')
+      index += 2
+      while (index < source.length) {
+        const commentChar = source[index]
+        const commentNext = source[index + 1]
+        if (commentChar === '*' && commentNext === '/') {
+          output.push(' ', ' ')
+          index += 1
+          break
+        }
+        output.push(commentChar === '\n' || commentChar === '\r' ? commentChar : ' ')
+        index += 1
+      }
+      continue
+    }
+    output.push(char)
+  }
+  return output.join('')
+}
+
+/** @param {string} source @returns {string} */
+function stripJsonTrailingCommas(source) {
+  const output = []
+  let inString = false
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index]
+    if (inString) {
+      output.push(char)
+      if (char === '\\') {
+        const escaped = source[index + 1]
+        if (escaped !== undefined) {
+          output.push(escaped)
+          index += 1
+        }
+      } else if (char === '"') {
+        inString = false
+      }
+      continue
+    }
+    if (char === '"') {
+      inString = true
+      output.push(char)
+      continue
+    }
+    if (char === ',') {
+      let nextIndex = index + 1
+      while (/\s/.test(source[nextIndex] ?? '')) nextIndex += 1
+      if (source[nextIndex] === '}' || source[nextIndex] === ']') continue
+    }
+    output.push(char)
+  }
+  return output.join('')
+}
+
+/** @param {string} source @returns {unknown} */
+function parseJsonc(source) {
+  return JSON.parse(stripJsonTrailingCommas(stripJsonComments(source)))
+}
+
 /**
  * Merge a baseline Oxc config (.oxfmtrc.json / .oxlintrc.json) with the
  * consumer's current config. The baseline owns every key it defines, except
@@ -828,7 +939,9 @@ function mergeGitignore(baseline, existing) {
  * migrations or by the repository) are preserved so repeated syncs never
  * churn them. Keys the baseline does not define (e.g. a repository-owned
  * `overrides` block) belong to the consumer and are preserved as well, so
- * a sync never silently drops repository-owned configuration.
+ * a sync never silently drops repository-owned configuration. Consumer
+ * category values are merged last so explicit category overrides survive the
+ * baseline's default category levels.
  *
  * When the merged semantics already match the consumer file, the exact
  * existing bytes are returned untouched: rewriting canonical JSON here
@@ -840,23 +953,28 @@ function mergeIgnorePatternsConfig(baseline, existing) {
   /** @type {Record<string, any>} */
   let consumer = {}
   try {
-    consumer = JSON.parse(existing)
-    if (consumer === null || typeof consumer !== 'object' || Array.isArray(consumer))
-      return baseline
+    const parsed = parseJsonc(existing)
+    if (!isJsonObject(parsed)) return baseline
+    consumer = parsed
   } catch {
     return baseline
   }
   /** @type {Record<string, any>} */
   let config = {}
   try {
-    config = JSON.parse(baseline)
-    if (config === null || typeof config !== 'object' || Array.isArray(config)) return baseline
+    const parsed = parseJsonc(baseline)
+    if (!isJsonObject(parsed)) return baseline
+    config = parsed
   } catch {
     return baseline
   }
   /** @type {Record<string, any>} */
   const merged = { ...config }
   for (const [key, value] of Object.entries(consumer)) {
+    if (key === 'categories' && isJsonObject(merged.categories) && isJsonObject(value)) {
+      merged.categories = { ...merged.categories, ...value }
+      continue
+    }
     if (!(key in merged)) merged[key] = value
   }
   const extra = Array.isArray(consumer.ignorePatterns) ? consumer.ignorePatterns : []
@@ -1006,7 +1124,7 @@ function renderConfigLine(key, value) {
   return needsQuotes ? `${key}: '${value.replace(/'/g, "''")}'` : `${key}: ${value}`
 }
 /** @param {string} root */
-function readPackageVersion(root) {
+export function readPackageVersion(root) {
   try {
     return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version ?? '0.0.0'
   } catch {

package/src/runtime.mjs

@@ -327,34 +327,11 @@ function hasDependencyManifest(ecosystem) {
   return false
 }
 
-/**
- * Detect repository-owned ESLint setup: an eslint dependency (or script
- * reference), or a tracked flat/legacy config file. Repositories without any
- * of these have nothing for the fallback runner to enforce, so lint skips
- * instead of forcing a network fetch of ESLint in CI.
- * @returns {boolean}
- */
-function hasEslintSetup() {
-  const pkg = readPackage() ?? {}
-  const scripts = pkg.scripts ?? {}
-  const dependencies = {
-    ...pkg.dependencies,
-    ...pkg.devDependencies,
-    ...pkg.optionalDependencies,
-    ...pkg.peerDependencies,
-  }
-  if (dependencies.eslint) return true
-  if (Object.values(scripts).some((value) => /\beslint\b/.test(String(value)))) return true
-  return repositoryTestFiles().some((file) =>
-    /(^|\/)(\.eslintrc[^/]*|eslint\.config\.[^/]*)$/.test(file)
-  )
-}
-
 /**
  * Detect repository-owned Oxlint setup: an oxlint dependency (or script
  * reference) or a tracked `.oxlintrc.json` / `oxlint.config.*` file. Oxlint
- * is the baseline's preferred JavaScript linter; the ESLint fallback only
- * runs when no Oxlint setup exists.
+ * is the baseline's preferred JavaScript linter; repositories without one
+ * fall back to their own `lint` script if defined.
  * @returns {boolean}
  */
 function hasOxlintSetup() {
@@ -376,8 +353,8 @@ function hasOxlintSetup() {
 /**
  * Detect repository-owned Oxfmt setup: an oxfmt dependency (or script
  * reference) or a tracked `.oxfmtrc.json` / `oxfmt.config.*` file. Oxfmt is
- * the baseline's preferred JavaScript formatter; the Prettier fallback only
- * runs when no Oxfmt setup exists.
+ * the baseline's formatter; repositories using a different formatter opt out
+ * through their own `format`/`fmt` scripts, which the script fallback honors.
  * @returns {boolean}
  */
 function hasOxfmtSetup() {
@@ -415,12 +392,13 @@ function ci(task) {
     if (
       !scripted &&
       (hasLanguage('typescript') || hasLanguage('javascript')) &&
-      hasRootJavascriptProject()
+      hasRootJavascriptProject() &&
+      hasOxfmtSetup()
     ) {
-      // Oxfmt is the preferred formatter; Prettier remains the fallback for
-      // repositories that have not migrated.
-      if (hasOxfmtSetup()) runTool('oxfmt', ['--check', '.'])
-      else runTool('prettier', ['--check', '.'])
+      // Oxfmt is the baseline's formatter. Repositories that use a different
+      // formatter keep full control through their own `format`/`fmt` scripts,
+      // which the runScript fallback above already honors.
+      runTool('oxfmt', ['--check', '.'])
     }
     if (hasLanguage('python') && hasRootPythonProject()) runTool('ruff', ['format', '--check', '.'])
     if (hasLanguage('rust') && hasRootRustProject()) run('cargo', ['fmt', '--check'])
@@ -431,12 +409,13 @@ function ci(task) {
     if (
       !scripted &&
       (hasLanguage('typescript') || hasLanguage('javascript')) &&
-      hasRootJavascriptProject()
+      hasRootJavascriptProject() &&
+      hasOxlintSetup()
     ) {
-      // Oxlint is the preferred linter; ESLint remains the fallback for
-      // repositories that have not migrated.
-      if (hasOxlintSetup()) runTool('oxlint', [])
-      else if (hasEslintSetup()) runTool('eslint', ['.'])
+      // Oxlint is the baseline's linter. Repositories that use a different
+      // linter keep full control through their own `lint` script, which the
+      // runScript fallback above already honors.
+      runTool('oxlint', [])
     }
     if (hasLanguage('python') && hasRootPythonProject()) runTool('ruff', ['check', '.'])
     if (hasLanguage('rust') && hasRootRustProject())