code-foundry 1.9.13 → 1.10.1

package/.github/CONTRIBUTING.md

@@ -32,6 +32,27 @@ Agents must not:
 - Change branch protections, secrets, deployments, or external systems unless that action is explicitly in scope.
 - Claim completion when tests, deployment checks, or required reviews are still pending.
 
+<!-- code-foundry-managed: pull-request-policy -->
+
+### Pull request readiness (mandatory)
+
+This repository uses the `direct` workflow. Topic pull requests target `main`.
+
+- Open every ordinary pull request as a draft. Use `gh pr create --draft` or
+  set `draft: true` in the GitHub API; never create a ready ordinary pull
+  request as a shortcut.
+- Keep ordinary pull requests in draft while making commits. The generated
+  Draft Guard resets a ready ordinary pull request to draft on creation,
+  reopening, or a new commit, and runner-heavy validation starts only after an
+  explicit `ready_for_review` transition.
+- Run local validation and finish review preparation before marking an ordinary
+  pull request ready. After any later commit, mark it ready again only after
+  the current head is ready for review.
+- Release Please version pull requests are managed by the Code Foundry release
+  workflow; do not manually change their draft state unless the workflow asks.
+
+<!-- /code-foundry-managed: pull-request-policy -->
+
 ## Branching model
 
 ```text
@@ -160,11 +181,11 @@ Keep pull requests focused and reviewable. Include screenshots or recordings for
 | Exact Release Please pull request targeting `main` | Full validation: CI, full tests, Security, and CodeQL, ending in `Validation / Gate`  |
 | Scheduled or manual validation                     | Full audit tier                                                                       |
 | Push to a working branch                           | Draft PR workflow                                                                     |
-| Push to `main`                                     | Release workflow; canonical validation already ran on the merged PR                   |
+| Push to `main`                                     | Release workflow plus default-branch CodeQL scan; validation ran on the merged PR     |
 
-Draft pull requests do not start validation. Marking a pull request ready for review starts the applicable validation tier. Convert it back to draft after an update, then mark it ready again after every update so the required checks attach to the current head. Converting it to draft runs only the lightweight cancellation control.
+Draft pull requests do not start validation. The lightweight Draft Guard also converts ordinary pull requests opened, reopened, or updated while ready back to draft; it never checks out pull-request code and it excludes Release Please version heads, whose release workflow owns their state. Marking a pull request ready for review starts the applicable validation tier. Convert it back to draft after an update, then mark it ready again after every update so the required checks attach to the current head. Converting it to draft runs only the lightweight cancellation control.
 
-Pull-request validation keys concurrency by event and pull-request head, so a newer update cancels its superseded run. Scheduled and manual audits use a separate caller pinned to the protected default branch; this prevents caller-selected runtime code from executing with default-branch cache access. Both callers use the mode-aware orchestrator, which fans out only the required jobs and concludes with the stable aggregate gate.
+Pull-request validation keys concurrency by event and pull-request head, so a newer update cancels its superseded run. Scheduled and manual audits use a separate caller pinned to the protected default branch; this prevents caller-selected runtime code from executing with default-branch cache access. Pull-request and scheduled/manual callers use the mode-aware orchestrator, which fans out only the required jobs and concludes with the stable aggregate gate. Main pushes run the default-branch CodeQL lane separately.
 
 Required checks are enforced by branch protection rulesets/branch protection. Do not duplicate their checklists in the pull request description; document validation commands and results instead.
 

package/.github/workflows/draft-enforcement_self-ci.yml

@@ -0,0 +1,79 @@
+name: Code Foundry Draft Guard
+
+on:
+  # This workflow runs from the trusted base branch and only reads pull-request
+  # metadata before changing draft state. It never checks out or executes PR code.
+  pull_request_target:
+    branches: [main, staging]
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+permissions:
+  pull-requests: write
+
+concurrency:
+  group: code-foundry-draft-guard-${{ github.repository }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  enforce:
+    name: Draft Guard / Enforce
+    if: vars.CI_BILLING_PAUSED != 'true'
+    runs-on: ubuntu-slim
+    timeout-minutes: 5
+    steps:
+      - name: Keep ordinary pull requests in draft
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          EVENT_UPDATED_AT: ${{ github.event.pull_request.updated_at }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          if [ -z "$EVENT_HEAD_SHA" ] || [ -z "$EVENT_UPDATED_AT" ] || [ -z "$PR_NUMBER" ]; then
+            echo '::error title=Draft guard cannot verify event freshness::The pull-request event did not include the required immutable metadata.'
+            exit 1
+          fi
+
+          read -r draft head_ref head_sha updated_at < <(
+            gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" \
+              --jq '[.draft, .head.ref, .head.sha, .updated_at] | @tsv'
+          )
+          if [ -z "$draft" ] || [ -z "$head_ref" ] || [ -z "$head_sha" ] || [ -z "$updated_at" ]; then
+            echo '::error title=Draft guard cannot verify current state::The GitHub API response did not include the required pull-request metadata.'
+            exit 1
+          fi
+
+          # Release Please owns the state of generated version PRs. Its release
+          # workflow deliberately resets and readies these PRs before merging.
+          case "$head_ref" in
+            release-please--branches--main|release-please--branches--main--*)
+              echo "Release Please head $head_ref is managed by the release workflow; leaving its draft state unchanged."
+              exit 0
+              ;;
+          esac
+
+          # A newer state transition or commit superseded this event. Do not
+          # undo a user's later explicit readiness decision with a stale event.
+          if [ "$head_sha" != "$EVENT_HEAD_SHA" ] || [ "$updated_at" != "$EVENT_UPDATED_AT" ]; then
+            echo 'A newer pull-request state or head commit superseded this draft-guard event; leaving the current state unchanged.'
+            exit 0
+          fi
+
+          if [ "$draft" = true ]; then
+            echo "Pull request #$PR_NUMBER is already a draft; no validation state change is needed."
+            exit 0
+          fi
+          if [ "$draft" != false ]; then
+            echo "::error title=Draft guard cannot verify current state::Unexpected draft value: $draft"
+            exit 1
+          fi
+
+          gh api \
+            --method PATCH \
+            "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" \
+            -F draft=true \
+            --silent >/dev/null
+          echo "Converted ordinary pull request #$PR_NUMBER to draft; runner-heavy validation waits for ready_for_review."

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

@@ -1,6 +1,8 @@
 name: Code Foundry
 
 on:
+  push:
+    branches: [main]
   pull_request:
     branches: [main, staging]
     types:
@@ -18,9 +20,9 @@ concurrency:
 jobs:
   mode:
     name: Mode
-    # The workflow is emitted only for ready_for_review, so draft pull requests
-    # register no skipped validation checks and allocate no validation runner.
-    if: vars.CI_BILLING_PAUSED != 'true'
+    # The mode classifier is only needed for pull requests. Main pushes use
+    # the dedicated default-branch CodeQL lane below.
+    if: vars.CI_BILLING_PAUSED != 'true' && github.event_name == 'pull_request'
     runs-on: ubuntu-slim
     timeout-minutes: 10
     permissions:
@@ -59,7 +61,7 @@ jobs:
   validation:
     name: Validation
     needs: mode
-    if: vars.CI_BILLING_PAUSED != 'true'
+    if: vars.CI_BILLING_PAUSED != 'true' && github.event_name == 'pull_request'
     # Reusable workflows can only maintain or reduce the caller job's scopes.
     # The audit tier needs security-events: write for CodeQL uploads.
     permissions:
@@ -87,3 +89,23 @@ jobs:
     secrets:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       NEXTAUTH_SECRET: ${{ secrets.NEXTAUTH_SECRET }}
+
+  # CodeQL requires a push analysis to populate default-branch code-scanning
+  # alerts. Keep the full validation gate pull-request-only so main pushes do
+  # not duplicate CI, test, or security work.
+  default-branch-codeql:
+    name: CodeQL (default branch)
+    if: vars.CI_BILLING_PAUSED != 'true' && github.event_name == 'push'
+    permissions:
+      actions: read
+      contents: read
+      packages: read
+      security-events: write
+    uses: ./.github/workflows/codeql.yml
+    with:
+      runtime-repository: 0xPlayerOne/code-foundry
+      runtime-ref: ${{ github.sha }}
+      runner: ubuntu-latest
+      rust-shards: '["all"]'
+      rust-threads: '1'
+      rust-max-parallel: 1

package/.oxfmtrc.json

@@ -3,5 +3,5 @@
   "singleQuote": true,
   "trailingComma": "es5",
   "printWidth": 100,
-  "ignorePatterns": ["CHANGELOG.md", ".github/.code-foundry", ".github/actions/"]
+  "ignorePatterns": ["CHANGELOG.md", ".github/.code-foundry", ".github/actions/", "plugin.json"]
 }

package/AGENTS.md

@@ -94,6 +94,29 @@ them:
 - Keep pull requests focused; merge with the canonical method only after
   required checks pass.
 
+<!-- code-foundry-managed: pull-request-policy -->
+
+## Code Foundry workflow policy (mandatory)
+
+This repository uses the `direct` workflow. Topic pull requests target `main`.
+
+- Open every ordinary pull request as a draft. Use `gh pr create --draft` or
+  set `draft: true` in the GitHub API; never create a ready ordinary pull
+  request as a shortcut.
+- Keep ordinary pull requests in draft while making commits. The generated
+  Draft Guard resets a ready ordinary pull request to draft on creation,
+  reopening, or a new commit, and runner-heavy validation starts only after an
+  explicit `ready_for_review` transition.
+- Run local validation and finish review preparation before marking an ordinary
+  pull request ready. After any later commit, mark it ready again only after
+  the current head is ready for review.
+- This contract is mandatory for every agent scope. Nested `AGENTS.md` files
+  may add stricter rules but must not weaken or replace it.
+- Release Please version pull requests are managed by the Code Foundry release
+  workflow; do not manually change their draft state unless the workflow asks.
+
+<!-- /code-foundry-managed: pull-request-policy -->
+
 ## Toolchain and dependencies
 
 - Follow `toolchain: auto` in `.github/code-foundry.yml`; use native tools by
@@ -154,7 +177,7 @@ If a check cannot run, state the exact reason. A skipped check is not a passing
 - Use per-workflow concurrency groups that cancel superseded runs while allowing independent workflows to run in parallel.
 - Keep setup language-aware and cache dependency downloads by lockfile; do not cache secrets, `node_modules`, virtual environments, or broad build output without a measured reason.
 - Use least-privilege permissions and pin action versions consistently with the template.
-- Keep CI, Test, Security, CodeQL, Draft PR, Release PR, and Release concerns separated.
+- Keep CI, Test, Security, CodeQL, Draft Guard, Draft PR, Release PR, and Release concerns separated.
 - Security and CodeQL may skip when repository visibility or GitHub plan support does not permit them. Do not make an unavailable check required.
 - Optional Turborepo Remote Caching uses `TURBO_TOKEN` and `TURBO_TEAM`; do not add Vercel deployment behavior just to enable caching.
 - Update branch protection when adding or renaming required job checks; verify the actual GitHub status context.

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.10.1](https://github.com/0xPlayerOne/code-foundry/compare/v1.10.0...v1.10.1) (2026-09-09)
+
+
+### Bug Fixes
+
+* **doctor:** honor shared config and correctly identify npm/Yarn lockfiles ([#533](https://github.com/0xPlayerOne/code-foundry/issues/533)) ([6464409](https://github.com/0xPlayerOne/code-foundry/commit/646440907ad3fc47f63e27b9621c8e0025459964))
+* **validation:** scan default branch with CodeQL on push ([#540](https://github.com/0xPlayerOne/code-foundry/issues/540)) ([98d8241](https://github.com/0xPlayerOne/code-foundry/commit/98d8241522c78e1b6d3f4f29a44053d33888edba))
+
+## [1.10.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.9.13...v1.10.0) (2026-09-08)
+
+
+### Features
+
+* **ci:** enforce draft pull request readiness ([#530](https://github.com/0xPlayerOne/code-foundry/issues/530)) ([fe62147](https://github.com/0xPlayerOne/code-foundry/commit/fe621477a46b49dee69a4c74c482e815a3e60b8d))
+
 ## [1.9.13](https://github.com/0xPlayerOne/code-foundry/compare/v1.9.12...v1.9.13) (2026-09-08)
 
 

package/README.md

@@ -36,7 +36,7 @@ contract. For normal updates, edit that file and run `npx code-foundry sync`.
 ## What it installs
 
 - Short workflow callers for pull-request validation, protected scheduled/manual
-  audits, Draft PR, Release PR, and Release.
+  audits, Draft Guard, Draft PR, Release PR, and Release.
 - A deterministic performance lane with ordered command support, stable result
   artifacts, and an optional shared Node package budget profile.
 - A small `.githooks/pre-commit` launcher with language-aware formatting and
@@ -70,14 +70,17 @@ when present and otherwise uses native language tooling; choose `native` or
 
 The standard workflow triggers are:
 
-- Pushes to `main` (and `staging` when `git_workflow: staging-release` is configured).
+- Pushes to `main` (and `staging` when `git_workflow: staging-release` is configured); main pushes also run the default-branch CodeQL scan.
 - Pull requests targeting `main` (and `staging` in the staging-release topology).
 - Draft PR automation for supported feature/fix branches.
 
 Automated feature/fix and staging-promotion pull requests open as drafts.
-Pull-request validation runs on the ready-for-review transition. After later
-commits, convert the PR to draft and mark it ready again so checks attach to
-the current head. Converting a PR to draft runs only the lightweight
+The trusted Draft Guard is a fallback for manually created or reopened ready
+PRs and for new commits to ordinary ready PRs: it converts them to drafts
+without checking out PR code. It verifies the event head and update timestamp
+before changing state, and excludes Release Please version PRs whose release
+workflow owns readiness. Pull-request validation runs only on the
+ready-for-review transition. Converting a PR to draft runs only the lightweight
 cancellation control. Scheduled and manually dispatched audits are unaffected.
 
 Jobs are language-aware and skip irrelevant setup inside the applicable

package/docs/INITIALIZATION.md

@@ -38,7 +38,16 @@ runtime, then run sync.
 
 Sync updates standard Code Foundry files only. It preserves application code,
 authored documentation, existing `.mise.toml` selections, and custom workflows
-such as deployment, search, Slither, or monitoring workflows.
+such as deployment, search, Slither, or monitoring workflows. A missing
+`AGENTS.md` receives the baseline agent contract. If another initializer has
+created an unmarked `AGENTS.md` or `.github/CONTRIBUTING.md`, sync preserves its
+surrounding text and adds or refreshes only the marked Code Foundry policy block;
+this lets later syncs restore mandatory pull-request rules without replacing
+agent-specific instructions. Marked generated policy documents continue to
+receive topology-aware baseline updates, and missing configuration keys are
+added without changing existing values. The Oxfmt baseline also ignores
+`plugin.json`, whose serialization is owned by Release Please; plugin manifest
+semantics remain covered by repository tests rather than a formatter rewrite.
 
 The environment bootstrap enables repository hooks and uses mise only when an
 existing `.mise.toml` is present or `toolchain: mise` is selected. Otherwise it

package/docs/WORKFLOWS.md

@@ -4,20 +4,30 @@
 
 Validation uses two callers so pull-request code and default-branch-capable
 audit events never share a caller-selected runtime ref. The canonical
-`validation.yml` caller handles pull requests only:
+`validation.yml` caller handles pull requests and a lightweight default-branch
+CodeQL lane:
 
 ```yaml
+push:
+  branches: [main] # CodeQL only
 pull_request:
   branches: [main, staging] # staging-release topology
   # direct topology: branches: [main]
 ```
 
-The generated validation caller listens only for `ready_for_review`, so draft
-pull requests register no validation checks and allocate no validation runner.
-After any later update, convert the pull request to draft and mark it ready
-again so required checks attach to the current head. A separate lightweight
-draft-control caller listens for `converted_to_draft` and cancels queued or
-running pull-request workflows without creating skipped validation jobs.
+The generated validation caller listens for `ready_for_review` and `push` to
+`main`. Draft pull requests register no validation checks and allocate no
+validation runner; main pushes run only the default-branch CodeQL lane, while
+full validation remains pull-request-only.
+A separate lightweight Draft Guard runs from the trusted base branch on
+`opened`, `reopened`, and `synchronize`; it converts ordinary ready pull
+requests back to draft without checking out pull-request code. It rechecks the
+current head and update timestamp before mutating state, so a stale event
+cannot undo a later draft or ready transition. Release Please version heads are
+excluded because the release workflow owns their state. A separate draft-control
+caller listens for `converted_to_draft` and cancels queued or running
+pull-request workflows without creating skipped validation jobs. Marking a pull
+request ready again starts validation for the current head.
 
 The separate `validation-audit.yml` caller is pinned to the configured released
 runtime and handles scheduled and manual audits:
@@ -39,7 +49,7 @@ Scheduled and manual runs select the audit tier in both topologies. Draft PR
 automation separately listens to supported topic-branch pushes and always
 opens those PRs as drafts. Promotion automation listens to `staging` pushes
 (staging-release only) and also always opens its PR as a draft. Release
-automation listens to `main` pushes.
+automation and default-branch CodeQL listen to `main` pushes.
 Custom deployment, indexing, search, Slither, or other workflows are
 repository-owned extensions and should use the same ready-transition policy.
 
@@ -91,15 +101,16 @@ opt in or out without a code change.
 
 ## Standard workflow responsibilities
 
-| Workflow   | Responsibility                                                    |
-| ---------- | ----------------------------------------------------------------- |
-| CI         | Format, lint, type-check, and build                               |
-| Test       | Unit, standardized performance, integration, E2E, and smoke tests |
-| Security   | Profile, audits, and public-only Dependency Review                |
-| CodeQL     | GitHub-native code scanning, kept separate from CI                |
-| Draft PR   | Create/update development pull requests                           |
-| Release PR | Promote `staging` into `main` (staging-release topology only)     |
-| Release    | Release Please, GitHub release, and optional npm publication      |
+| Workflow    | Responsibility                                                    |
+| ----------- | ----------------------------------------------------------------- |
+| CI          | Format, lint, type-check, and build                               |
+| Test        | Unit, standardized performance, integration, E2E, and smoke tests |
+| Security    | Profile, audits, and public-only Dependency Review                |
+| CodeQL      | GitHub-native code scanning, kept separate from CI                |
+| Draft PR    | Create/update development pull requests                           |
+| Draft Guard | Keep ordinary PRs draft until `ready_for_review`                  |
+| Release PR  | Promote `staging` into `main` (staging-release topology only)     |
+| Release     | Release Please, GitHub release, and optional npm publication      |
 
 Use concise job names such as `CI / Format`, `Test / Unit`, and
 `CodeQL / Analyze (Python)`. Per-language CodeQL analyzers (Rust shards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.9.13",
+  "version": "1.10.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

@@ -5,6 +5,7 @@ import { join, resolve } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { includesValue, readConfig } from '../lib/config.mjs'
 import { recommendRunners, resolveProfile } from '../lib/profile.mjs'
+import { packageManagerForLockfile } from '../lib/lockfiles.mjs'
 import { doctorGithub } from '../lib/github-doctor.mjs'
 import { isGeneratedEventCaller } from './sync.mjs'
 
@@ -69,9 +70,7 @@ export function doctor(root, options = {}) {
     if (lockfiles.length > 1) error('multiple JavaScript lockfiles found; keep one package manager')
     if (packageJson.packageManager && lockfiles.length) {
       const declared = String(packageJson.packageManager).split('@')[0]
-      const actual = lockfiles[0]?.startsWith('bun')
-        ? 'bun'
-        : lockfiles[0]?.split('-')[0].replace('.yaml', '')
+      const actual = packageManagerForLockfile(lockfiles[0])
       if (actual && declared !== actual)
         error(`packageManager (${declared}) does not match ${actual} lockfile`)
     }
@@ -150,9 +149,19 @@ export function doctor(root, options = {}) {
   const validationEnabled =
     includesValue(features, 'validation') ||
     ['ci', 'test', 'security', 'codeql'].some((legacy) => includesValue(features, legacy))
-  for (const name of ['validation', 'draft-control', 'draft-pr', 'release-pr', 'release']) {
+  for (const name of [
+    'validation',
+    'draft-control',
+    'draft-enforcement',
+    'draft-pr',
+    'release-pr',
+    'release',
+  ]) {
     if (name === 'release-pr' && workflow !== 'staging-release') continue
-    const enabled = name === 'draft-control' ? validationEnabled : includesValue(features, name)
+    const enabled =
+      name === 'draft-control' || name === 'draft-enforcement'
+        ? validationEnabled
+        : includesValue(features, name)
     const candidates = [
       join(target, `.github/workflows/${name}.yml`),
       join(target, `.github/workflows/${name}_self-ci.yml`),

package/src/commands/release.mjs

@@ -371,6 +371,7 @@ function deliverReconciliationPullRequest(target, base, head, state, targetSha,
     title,
     '--body',
     body,
+    '--draft',
   ])
   if (created.status !== 0) {
     // A concurrent run may have created the pull request between our list

package/src/commands/sync.mjs

@@ -44,6 +44,7 @@ const standardFiles = [
   '.github/workflows/validation.yml',
   '.github/workflows/validation-audit.yml',
   '.github/workflows/draft-control.yml',
+  '.github/workflows/draft-enforcement.yml',
   '.github/workflows/draft-pr.yml',
   '.github/workflows/release-pr.yml',
   '.github/workflows/release.yml',
@@ -221,10 +222,6 @@ export function syncRepository(options) {
     const sourceFile = sourcePath(source, file)
     if (!existsSync(sourceFile)) throw new Error(`Template file missing: ${file}`)
     const destination = join(target, file)
-    if (!force && protectedFiles.has(file) && existsSync(destination)) {
-      const existing = readFileSync(destination, 'utf8')
-      if (!isLegacyManagedDoc(file, existing) && !isManagedConfigPolicy(file, existing)) continue
-    }
     if (
       (file === 'LICENSE' || file === 'NOTICE') &&
       license === 'preserve' &&
@@ -267,6 +264,19 @@ export function syncRepository(options) {
         mergeIgnorePatternsConfig(content.toString('utf8'), readFileSync(destination, 'utf8'))
       )
     }
+    if (!force && protectedFiles.has(file) && existsSync(destination)) {
+      const existing = readFileSync(destination, 'utf8')
+      if (!isLegacyManagedDoc(file, existing) && !isManagedConfigPolicy(file, existing)) {
+        if (configAwarePolicyFiles.has(file)) {
+          const merged = mergeManagedPolicyBlocks(existing, content.toString('utf8'))
+          if (merged !== existing) {
+            changed.push(file)
+            writeOrReport(destination, merged, dryRun)
+          }
+        }
+        continue
+      }
+    }
     if (!existsSync(destination) || !buffersEqual(content, readFileSync(destination))) {
       changed.push(file)
       writeOrReport(destination, content, dryRun)
@@ -478,7 +488,12 @@ function shouldInclude(file, languages, features, config) {
   // the configuration or the variable enables it and the API key exists.
   if (file === '.github/workflows/opencode-security.yml') return true
   const workflow = file.match(/^\.github\/workflows\/([^/]+)\.yml$/)?.[1]
-  if (workflow === 'draft-control') return true
+  if (workflow === 'draft-control' || workflow === 'draft-enforcement') {
+    return (
+      includesValue(features, 'validation') ||
+      LEGACY_GENERATED_CALLERS.some((legacy) => includesValue(features, legacy))
+    )
+  }
   // The staging promotion caller only exists in the staging-release topology;
   // direct repositories open feature branches into main and need no promotion.
   if (workflow === 'release-pr' && !isStagingRelease(config.git_workflow)) return false
@@ -522,12 +537,15 @@ function renderWorkflow(content, config, repository, ref, rustCodeql) {
   let rendered = content.replaceAll(localPrefix, remotePrefix)
   // An explicitly unavailable CodeQL capability selects an orchestrator that
   // omits the job entirely, so GitHub does not register a misleading skipped
-  // check on every pull request. `auto` retains runtime capability detection.
+  // check on every pull request or an unused main-push run. `auto` retains
+  // runtime capability detection.
   if (configured(config.codeql, 'auto') === 'false') {
     rendered = rendered.replaceAll(
       `${remotePrefix}validation.yml`,
       `${remotePrefix}validation-no-codeql.yml`
     )
+    rendered = removeWorkflowBlock(rendered, 'default-branch-codeql')
+    rendered = removeWorkflowBlock(rendered, 'push')
   }
   rendered = rendered.replace(
     new RegExp(`${escapeRegExp(remotePrefix)}([^\\s@]+)`, 'g'),
@@ -625,6 +643,25 @@ function renderWorkflow(content, config, repository, ref, rustCodeql) {
   return rendered
 }
 
+/**
+ * Remove a root-level YAML block by id while preserving the surrounding file.
+ * This is used for workflow jobs and triggers whose feature is disabled by
+ * configuration.
+ * @param {string} content
+ * @param {string} blockId
+ * @returns {string}
+ */
+function removeWorkflowBlock(content, blockId) {
+  const lines = content.split('\n')
+  const start = lines.findIndex((line) => line === `  ${blockId}:`)
+  if (start === -1) return content
+  let end = start + 1
+  while (end < lines.length && !/^  [A-Za-z0-9_-]+:\s*$/.test(lines[end])) end += 1
+  lines.splice(start, end - start)
+  if (content.endsWith('\n') && lines.at(-1) !== '') lines.push('')
+  return lines.join('\n')
+}
+
 /**
  * Dependabot updates land on the repository's integration branch. Direct
  * repositories have no staging branch, so every update targets main. Cargo,
@@ -719,8 +756,16 @@ 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 **squashes** into `main` (`release_merge_strategy: squash`). Feature and release PRs land on `main` with squash merges. No integration branch exists; all pull requests target `main`.',
     ],
+    [
+      'This repository uses the `staging-release` workflow. Topic pull requests target `staging`; promotion pull requests target `main`.',
+      'This repository uses the `direct` workflow. Topic pull requests target `main`.',
+    ],
   ],
   '.github/CONTRIBUTING.md': [
+    [
+      'This repository uses the `staging-release` workflow. Topic pull requests target `staging`; promotion pull requests target `main`.',
+      'This repository uses the `direct` workflow. Topic pull requests target `main`.',
+    ],
     [
       '4. Branch from `staging` and target pull requests at `staging`; do not work directly on `main`.',
       '4. Branch from `main` and target pull requests at `main`; do not push directly to `main`.',
@@ -756,16 +801,16 @@ const DIRECT_DOC_REPLACEMENTS = {
       '7. Push to the fork and open a pull request targeting `main`.',
     ],
     [
-      '| Event                                              | Expected automation                                                                   |\n| -------------------------------------------------- | ------------------------------------------------------------------------------------- |\n| Draft pull request targeting `staging`             | No runner-heavy validation; run local checks before requesting review                 |\n| Ready pull request targeting `staging`             | Fast validation: CI plus unit tests, ending in `Validation / Gate`                    |\n| Draft ordinary pull request targeting `main`       | No runner-heavy validation; run local checks before requesting review                 |\n| Ready ordinary pull request targeting `main`       | Audit validation: CI, full tests, Security, and CodeQL, ending in `Validation / Gate` |\n| Exact Release Please pull request targeting `main` | Full validation: CI, full tests, Security, and CodeQL, ending in `Validation / Gate`  |\n| Scheduled or manual validation                     | Full audit tier                                                                       |\n| Push to a working branch                           | Draft PR workflow                                                                     |\n| Push to `staging`                                  | Promotion PR workflow; canonical validation waits for the PR event                    |\n| Push to `main`                                     | Release workflow; canonical validation already ran on the merged PR                   |\n',
-      '| Event                                              | Expected automation                                                                   |\n| -------------------------------------------------- | ------------------------------------------------------------------------------------- |\n| Draft pull request targeting `main`                | No runner-heavy validation; run local checks before requesting review                 |\n| Ready pull request targeting `main`                | Audit validation: CI, full tests, Security, and CodeQL, ending in `Validation / Gate` |\n| Exact Release Please pull request targeting `main` | Full validation: CI, full tests, Security, and CodeQL, ending in `Validation / Gate`  |\n| Scheduled or manual validation                     | Full audit tier                                                                       |\n| Push to a working branch                           | Draft PR workflow                                                                     |\n| Push to `main`                                     | Release workflow; canonical validation already ran on the merged PR                   |\n',
+      '| Event                                              | Expected automation                                                                   |\n| -------------------------------------------------- | ------------------------------------------------------------------------------------- |\n| Draft pull request targeting `staging`             | No runner-heavy validation; run local checks before requesting review                 |\n| Ready pull request targeting `staging`             | Fast validation: CI plus unit tests, ending in `Validation / Gate`                    |\n| Draft ordinary pull request targeting `main`       | No runner-heavy validation; run local checks before requesting review                 |\n| Ready ordinary pull request targeting `main`       | Audit validation: CI, full tests, Security, and CodeQL, ending in `Validation / Gate` |\n| Exact Release Please pull request targeting `main` | Full validation: CI, full tests, Security, and CodeQL, ending in `Validation / Gate`  |\n| Scheduled or manual validation                     | Full audit tier                                                                       |\n| Push to a working branch                           | Draft PR workflow                                                                     |\n| Push to `staging`                                  | Promotion PR workflow; canonical validation waits for the PR event                    |\n| Push to `main`                                     | Release workflow plus default-branch CodeQL scan; validation ran on the merged PR     |\n',
+      '| Event                                              | Expected automation                                                                   |\n| -------------------------------------------------- | ------------------------------------------------------------------------------------- |\n| Draft pull request targeting `main`                | No runner-heavy validation; run local checks before requesting review                 |\n| Ready pull request targeting `main`                | Audit validation: CI, full tests, Security, and CodeQL, ending in `Validation / Gate` |\n| Exact Release Please pull request targeting `main` | Full validation: CI, full tests, Security, and CodeQL, ending in `Validation / Gate`  |\n| Scheduled or manual validation                     | Full audit tier                                                                       |\n| Push to a working branch                           | Draft PR workflow                                                                     |\n| Push to `main`                                     | Release workflow plus default-branch CodeQL scan; validation ran on the merged PR     |\n',
     ],
     [
       '| 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` | Squash (`release_merge_strategy`) | Validation gate and release policy pass |\n',
     ],
     [
-      'Draft pull requests do not start runner-heavy validation. Marking a pull request ready for review starts the applicable validation tier; converting it back to draft cancels in-flight validation, and no replacement starts until it is ready again.',
-      'Draft pull requests do not start validation. Marking a pull request ready for review starts the applicable validation tier. Convert it back to draft after an update, then mark it ready again after every update so the required checks attach to the current head. Converting it to draft runs only the lightweight cancellation control.',
+      'Draft pull requests do not start runner-heavy validation. The lightweight Draft Guard also converts ordinary pull requests opened, reopened, or updated while ready back to draft; it never checks out pull-request code and it excludes Release Please version heads, whose release workflow owns their state. Marking a pull request ready for review starts the applicable validation tier. Convert it back to draft after an update, then mark it ready again after every update so the required checks attach to the current head; converting it back to draft cancels in-flight validation, and no replacement starts until it is ready again.',
+      'Draft pull requests do not start validation. The lightweight Draft Guard also converts ordinary pull requests opened, reopened, or updated while ready back to draft; it never checks out pull-request code and it excludes Release Please version heads, whose release workflow owns their state. Marking a pull request ready for review starts the applicable validation tier. Convert it back to draft after an update, then mark it ready again after every update so the required checks attach to the current head. Converting it to draft runs only the lightweight cancellation control.',
     ],
     ['1. Create a focused branch from `staging`.', '1. Create a focused branch from `main`.'],
   ],
@@ -1116,9 +1161,12 @@ function isLegacyManagedDoc(file, content) {
 
 /**
  * Config-aware policy documents are generated contracts: a normal sync must
- * refresh them after branch-topology or validation-policy edits. The marker
- * owns future copies. Exact scaffold signatures migrate older generated
- * copies without treating arbitrary repository documentation as managed.
+ * refresh generated copies after branch-topology or validation-policy edits.
+ * Unmarked consumer-owned documents receive only the explicitly marked policy
+ * blocks, so another agent's initializer cannot be overwritten. The top-level
+ * marker owns generated copies. Exact scaffold signatures migrate older
+ * generated copies without treating arbitrary repository documentation as
+ * managed.
  * @param {string} file
  * @param {string} content
  */
@@ -1157,6 +1205,45 @@ function git(target, args) {
   spawnSync('git', args, { cwd: target, stdio: 'ignore' })
 }
 
+/**
+ * Merge the marked policy blocks from a rendered baseline into a consumer-owned
+ * policy document. Unmarked AGENTS.md/CONTRIBUTING.md files are commonly
+ * generated by another agent initializer, so sync must add and refresh the
+ * Code Foundry contract without replacing the user's surrounding instructions.
+ * @param {string} existing
+ * @param {string} baseline
+ * @returns {string}
+ */
+function mergeManagedPolicyBlocks(existing, baseline) {
+  const blockPattern =
+    /<!-- code-foundry-managed: ([A-Za-z0-9_-]+) -->[\s\S]*?<!-- \/code-foundry-managed: \1 -->/g
+  const blocks = [...baseline.matchAll(blockPattern)]
+  if (!blocks.length) return existing
+
+  let merged = existing
+  for (const match of blocks) {
+    const id = match[1]
+    const block = match[0]
+    const start = `<!-- code-foundry-managed: ${id} -->`
+    const end = `<!-- /code-foundry-managed: ${id} -->`
+    const pattern = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`, 'g')
+    const occurrences = merged.match(pattern) ?? []
+    if (occurrences.length > 1) {
+      throw new Error(`Managed policy block appears more than once in consumer document: ${id}`)
+    }
+    if (occurrences.length === 1) {
+      merged = merged.replace(pattern, block)
+      continue
+    }
+    if (merged.includes(start) || merged.includes(end)) {
+      throw new Error(`Managed policy block is incomplete in consumer document: ${id}`)
+    }
+    const separator = merged.endsWith('\n\n') ? '' : merged.endsWith('\n') ? '\n' : '\n\n'
+    merged = `${merged}${separator}${block}\n`
+  }
+  return merged
+}
+
 /** @param {string} file @param {Buffer|string} content @param {boolean} dryRun */
 function writeOrReport(file, content, dryRun) {
   if (dryRun) {

package/src/lib/github-doctor.mjs

@@ -3,6 +3,7 @@
 import { readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { readConfig } from './config.mjs'
 
 /** @param {string} root @returns {{ errors: string[], warnings: string[], details: Record<string, unknown> }} */
 export function doctorGithub(root) {
@@ -306,22 +307,3 @@ function ghJson(args) {
 function commandExists(command) {
   return spawnSync(command, ['--version'], { stdio: 'ignore' }).status === 0
 }
-
-/** @param {string} root @returns {Record<string, string>} */
-function readConfig(root) {
-  const file = join(root, '.github/code-foundry.yml')
-  try {
-    return Object.fromEntries(
-      readFileSync(file, 'utf8')
-        .split(/\r?\n/)
-        .flatMap((line) => {
-          const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/)
-          return match
-            ? [[match[1], match[2].replace(/\s+#.*$/, '').replace(/^['"]|['"]$/g, '')]]
-            : []
-        })
-    )
-  } catch {
-    return {}
-  }
-}

package/src/lib/lockfiles.mjs

@@ -0,0 +1,15 @@
+// @ts-check
+
+/** @type {Readonly<Record<string, string>>} */
+const managers = Object.freeze({
+  'bun.lock': 'bun',
+  'bun.lockb': 'bun',
+  'pnpm-lock.yaml': 'pnpm',
+  'yarn.lock': 'yarn',
+  'package-lock.json': 'npm',
+})
+
+/** @param {string | undefined} file @returns {string | undefined} */
+export function packageManagerForLockfile(file) {
+  return file && Object.hasOwn(managers, file) ? managers[file] : undefined
+}