code-foundry 1.5.0 → 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/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/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

package/README.md

@@ -91,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

@@ -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`

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.5.0",
+  "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)
@@ -177,15 +181,17 @@ export function syncRepository(options) {
   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)
@@ -829,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
@@ -836,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
@@ -848,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 : []
@@ -1014,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 {