ci: cross-platform CI manual-only on dev (drop dev push); document CI policy

.github/workflows/catalog-async-contracts.yml

@@ -2,7 +2,7 @@ name: Catalog async contracts
 
 on:
   push:
-    branches: [dev, main, preview]
+    branches: [main, preview]
     paths:
       - src/**
       - scripts/diagnostics/windows-version-control/**
@@ -36,7 +36,7 @@ jobs:
       fail-fast: false
       matrix:
         # Pull requests run the ubuntu leg only; macos and windows run on push
-        # to dev/main/preview and on dispatch.
+        # to main/preview and on manual dispatch.
         os: ${{ fromJSON(github.event_name == 'pull_request' && '["ubuntu-latest"]' || '["ubuntu-latest","macos-latest","windows-latest"]') }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7

.github/workflows/ci.yml

@@ -1,3 +1,11 @@
+# ============================================================================
+# CI POLICY (maintainer decision — do not change in a contributor PR)
+#  * Pull requests run ONLY the fast Ubuntu subset.
+#  * Full cross-platform (macOS/Windows) CI runs ONLY via manual
+#    workflow_dispatch and on push to main/preview (release lines).
+#  * NEVER add a dev push trigger or pull_request runs for macOS/Windows jobs.
+#  PRs that change this policy will be closed. See AGENTS.md "CI policy".
+# ============================================================================
 name: Cross-platform CI
 
 on:
@@ -25,17 +33,17 @@ on:
     # Pull requests run only the fast Ubuntu subset. Every macOS and Windows
     # job (and the macOS/Windows legs of the keyring, npm-global, setup-action
     # and remote-helper matrices) is skipped on `pull_request` and runs after
-    # merge instead, on the `push:` below, plus workflow_dispatch and the
-    # nightly schedule.
+    # merge instead, via workflow_dispatch, the main/preview `push:` below and
+    # the nightly schedule.
     #
-    # `push:` covers dev so every merge into the integration branch gets the
-    # cross-platform evidence that pull requests no longer carry. main and
-    # preview MUST stay: release.yml requires a successful push-event
+    # `push:` is pinned to the release lines. dev is deliberately absent:
+    # cross-platform evidence for dev is run by hand via workflow_dispatch.
+    # main and preview MUST stay: release.yml requires a successful push-event
     # Cross-platform CI run for the exact release SHA and states that a
     # pull-request run does not qualify, so removing either branch breaks
     # publication.
   push:
-    branches: [dev, main, preview]
+    branches: [main, preview]
     paths:
       - "Dockerfile"
       - "compose.yaml"
@@ -822,7 +830,7 @@ jobs:
     name: macos ${{ matrix.shard }}/3
     needs: changes
     # Never on pull requests: macOS legs run after merge, on push to
-    # dev/main/preview, and on dispatch and the schedule.
+    # main/preview, and on dispatch and the schedule.
     if: github.event_name != 'pull_request'
     runs-on: macos-latest
     # Three shards. Unsharded, this job was the critical path on every green dev

.github/workflows/codex-queue-helpers.yml

@@ -8,13 +8,15 @@ on:
       - 'docs-site/src/content/docs/guides/composer-usage-gate-fallback.md'
       - '.github/workflows/codex-queue-helpers.yml'
   push:
-    branches: [dev, main, preview]
+    branches: [main, preview]
     paths:
       - 'scripts/codex-queue.*'
       - 'docs-site/astro.config.mjs'
       - 'docs-site/src/content/docs/guides/composer-usage-gate-fallback.md'
       - '.github/workflows/codex-queue-helpers.yml'
 
+  workflow_dispatch:
+
 permissions:
   contents: read
 

.github/workflows/service-lifecycle.yml

@@ -24,12 +24,12 @@ on:
       # produced no run and the gate dead-ended until a manual dispatch.
       - ".github/workflows/release.yml"
   push:
-    # dev plus the release lines. Pull requests run only the Linux leg, so the
-    # macOS and Windows legs run here after merge into dev. main and preview
+    # Release lines only (no dev: cross-platform legs run on dev by manual
+    # workflow_dispatch). Pull requests run only the Linux leg. main and preview
     # must stay: release.yml needs a successful push run for the exact release
     # SHA, and scripts/release.ts only releases from main or preview. Without a
     # branch filter every feature-branch push would re-run all three legs.
-    branches: [dev, main, preview]
+    branches: [main, preview]
     paths:
       - "src/service.ts"
       # Keep in sync with the release.yml service-gate regex (see above).
@@ -177,7 +177,7 @@ jobs:
           fi
 
   macos-launchd:
-    # Pull requests run the Linux leg only; macOS runs after merge, on push.
+    # Pull requests run the Linux leg only; macOS runs on manual dispatch and main/preview push.
     if: github.event_name != 'pull_request'
     runs-on: macos-latest
     timeout-minutes: 10
@@ -257,7 +257,7 @@ jobs:
           fi
 
   windows-schtasks:
-    # Pull requests run the Linux leg only; Windows runs after merge, on push.
+    # Pull requests run the Linux leg only; Windows runs on manual dispatch and main/preview push.
     if: github.event_name != 'pull_request'
     runs-on: windows-latest
     timeout-minutes: 10

AGENTS.md

@@ -365,6 +365,14 @@ than nudged.
   recorded in [`CREDITS.md`](./CREDITS.md); `missing_coauthor_credit` in
   `.github/scripts/pr-carry-attribution.cjs` is why the list should not grow.
 
+## CI policy (maintainer decision — do not change)
+
+- Pull requests run **only the fast Ubuntu subset**.
+- Full cross-platform (macOS/Windows) CI runs **only** via manual
+  `workflow_dispatch` and on push to `main`/`preview` (release lines).
+- **Never** add a `dev` push trigger, or `pull_request` runs for macOS/Windows
+  jobs, to any workflow. PRs that change this policy will be closed.
+
 ## Branch policy
 
 - `dev` — the single integration branch and the target for every pull request.

CONTRIBUTING.md

@@ -36,6 +36,14 @@ Source development requires the `bun` CLI on your `PATH`. The published npm pack
 Bun runtime for end users. Package scripts such as `bun run test` and `bun run prepush` may resolve
 Bun through that bundled dependency.
 
+## CI policy (maintainer decision — do not change)
+
+- Pull requests run **only the fast Ubuntu subset**.
+- Full cross-platform (macOS/Windows) CI runs **only** via manual
+  `workflow_dispatch` and on push to `main`/`preview` (release lines).
+- **Never** add a `dev` push trigger, or `pull_request` runs for macOS/Windows
+  jobs, to any workflow. PRs that change this policy will be closed.
+
 ## Pull request contract
 
 A ready-for-review PR is the author's claim that the change is complete, understood, tested, and suitable for merging. Opening a PR does not transfer responsibility for the branch to maintainers.

tests/ci-workflows/ci-review-lanes.test.ts

@@ -61,11 +61,11 @@ describe("CI review lanes", () => {
       }
     }
 
-    // The push trigger covers dev and the release lines. main and preview MUST
+    // The push trigger is pinned to the release lines. main and preview MUST
     // stay because release.yml requires a successful push-event run for the
     // exact release SHA and states that a pull-request run does not qualify.
-    // dev is required because pull requests run only the fast Ubuntu subset:
-    // the macOS and Windows legs run after merge, on the push into dev.
+    // dev is deliberately absent (CI policy): cross-platform legs run on dev
+    // only by manual workflow_dispatch.
     const ci = Bun.YAML.parse(await readText(".github/workflows/ci.yml")) as {
       on?: {
         push?: { branches?: string[]; paths?: string[] };
@@ -74,7 +74,7 @@ describe("CI review lanes", () => {
       jobs?: Record<string, Record<string, unknown> | undefined>;
     };
     expect([...(ci.on?.push?.branches ?? [])].sort())
-      .toEqual(["dev", "main", "preview"]);
+      .toEqual(["main", "preview"]);
 
     // The PR trigger must carry NO base-branch filter, and the two triggers
     // differ on purpose. GitHub matches `branches:` against the BASE ref, so

tests/ci-workflows/ci-scope-reduction.test.ts

@@ -300,13 +300,12 @@ function runGate(inputs: GateInputs, results: Record<string, string>): { gatedJo
 }
 
 describe("the push trigger", () => {
-  test("carries dev, main and preview", () => {
+  test("carries main and preview, and never dev", () => {
     // main and preview must stay: release.yml requires a successful push-event
     // run for the exact release SHA and states that a pull_request run does not
-    // qualify, so removing either breaks publication. dev is required because
-    // pull requests run only the fast Ubuntu subset: the macOS and Windows legs
-    // run after merge, on the push into dev.
-    expect([...(workflow.on?.push?.branches ?? [])].sort()).toEqual(["dev", "main", "preview"]);
+    // qualify, so removing either breaks publication. dev is deliberately absent
+    // (CI policy): cross-platform legs run on dev only by manual dispatch.
+    expect([...(workflow.on?.push?.branches ?? [])].sort()).toEqual(["main", "preview"]);
   });
 });