Consolidate and rename CI workflows

.github/workflows/windows-latest.yml → .github/workflows/build-cross-platform.yml

@@ -9,12 +9,12 @@
 #
 #     - To trigger manual generation invoke:
 #
-#         fallout --generate-configuration GitHubActions_windows-latest --host GitHubActions
+#         fallout --generate-configuration GitHubActions_build-cross-platform --host GitHubActions
 #
 # </auto-generated>
 # ------------------------------------------------------------------------------
 
-name: windows-latest
+name: build-cross-platform
 
 on:
   push:
@@ -34,6 +34,28 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  macos-latest:
+    name: macos-latest
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: 'Cache: .fallout/temp, ~/.nuget/packages'
+        uses: actions/cache@v4
+        with:
+          path: |
+            .fallout/temp
+            ~/.nuget/packages
+          key: ${{ runner.os }}-${{ hashFiles('**/global.json', '**/*.csproj', '**/Directory.Packages.props') }}
+      - name: 'Setup: .NET SDK'
+        uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: global.json
+      - name: 'Restore: dotnet tools'
+        run: dotnet tool restore
+      - name: 'Run: Test, Pack'
+        run: dotnet fallout Test Pack
   windows-latest:
     name: windows-latest
     runs-on: windows-latest

.github/workflows/build-docs.yml

@@ -0,0 +1,40 @@
+# Hand-written (not auto-generated). Companion to build.yml.
+#
+# Why this exists:
+#   - main branch protection requires the `ubuntu-latest` status check (the job
+#     name emitted by build.yml — branch protection keys on the job, not the
+#     workflow file/name).
+#   - build.yml has `paths-ignore: docs/**, .assets/**, **/*.md` so it doesn't
+#     fire on docs-only PRs.
+#   - Without a substitute, docs-only PRs sit BLOCKED waiting for a check that
+#     never reports.
+#
+# This workflow fires on the inverse path set (docs-only changes), runs nothing
+# of substance, and reports success under the same `ubuntu-latest` status-check
+# context — satisfying the protection rule without spending CI minutes on a real
+# build.
+#
+# Keep the job name `ubuntu-latest` aligned with build.yml so both files produce
+# a status check named `ubuntu-latest`; the workflow `name:` mirrors build.yml's
+# `build` so docs-only runs appear under the same workflow in the Actions tab.
+
+name: build
+
+on:
+  pull_request:
+    branches:
+      - main
+      - 'release/*'
+      - 'support/*'
+    paths:
+      - 'docs/**'
+      - '.assets/**'
+      - '**/*.md'
+
+jobs:
+  ubuntu-latest:
+    name: ubuntu-latest
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Skip: docs-only PR, no build needed'
+        run: echo "Docs-only change — ubuntu-latest validation skipped via .github/workflows/build-docs.yml."

.github/workflows/ubuntu-latest.yml → .github/workflows/build.yml

@@ -9,12 +9,12 @@
 #
 #     - To trigger manual generation invoke:
 #
-#         fallout --generate-configuration GitHubActions_ubuntu-latest --host GitHubActions
+#         fallout --generate-configuration GitHubActions_build --host GitHubActions
 #
 # </auto-generated>
 # ------------------------------------------------------------------------------
 
-name: ubuntu-latest
+name: build
 
 on:
   pull_request:

.github/workflows/preview.yml → .github/workflows/publish-packages-preview.yml

@@ -14,11 +14,13 @@
 #
 # `main` is the sole continuous prerelease lane (ADR-0008 collapsed the former
 # `experimental` `-alpha` lane into `main`). Stable + legacy releases are
-# deliberate and tag-triggered — see release.yml.
-# Cross-platform validation on `main` pushes is covered by macos-latest.yml /
-# windows-latest.yml; this workflow's job is publishing, not gating.
+# deliberate and tag-triggered — see publish-packages-release.yml.
+# Cross-platform validation (macOS/Windows) is gated to release intent
+# (build-cross-platform.yml) and does NOT run on `main` pushes; on `main` the
+# ubuntu-latest gate (build.yml) is the edge. This workflow's job is publishing,
+# not gating.
 
-name: preview
+name: publish-packages-preview
 
 on:
   push:
@@ -29,7 +31,7 @@ on:
       - '.assets/**'
       - '**/*.md'
 
-# Cancel a superseded preview build when a newer commit lands (#322). Never on release.yml.
+# Cancel a superseded preview build when a newer commit lands (#322). Never on publish-packages-release.yml.
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true

.github/workflows/release.yml → .github/workflows/publish-packages-release.yml

@@ -3,7 +3,7 @@
 # NuGetApiKey parameter, which would otherwise have to share a name).
 #
 # This is the DELIBERATE (production) release path. The fast test lane —
-# main (-preview), push → GitHub Packages — lives in preview.yml. See ADR-0004
+# main (-preview), push → GitHub Packages — lives in publish-packages-preview.yml. See ADR-0004
 # (amended 2026-05-30), as further amended by ADR-0008 (which collapsed the
 # former experimental/-alpha lane into main).
 #
@@ -33,7 +33,12 @@
 #
 # See docs/branching-and-release.md for the full runbook.
 
-name: release
+# The workflow `name:` below is load-bearing: Build.cs gates
+# ICreateGitHubRelease.CreateGitHubRelease on `github.workflow ==
+# ReleaseWorkflow` (the const in build/Build.CI.GitHubActions.cs). Keep the two
+# in sync — rename here and you must rename the const, or GitHub Releases stop
+# being cut.
+name: publish-packages-release
 
 on:
   push:

CONTRIBUTING.md

@@ -75,7 +75,7 @@ Tool wrapper JSON lives under `src/Fallout.Common/Tools/<Tool>/<Tool>.json`. Whe
 
 ### After opening a PR
 
-- The PR gate is `ubuntu-latest` only — fires on PRs against `main`, `release/*`, or `support/*`. Docs-only PRs hit a no-op shim workflow that reports the same status check name. `windows-latest` and `macos-latest` run post-merge for cross-platform validation.
+- The PR gate is the `ubuntu-latest` job (from `build.yml`) only — fires on PRs against `main`, `release/*`, or `support/*`. Docs-only PRs hit a no-op shim workflow (`build-docs.yml`) that reports the same status check name. `build-cross-platform.yml` runs Windows + macOS validation on `release/*` / `support/*` PRs and `v*` tag pushes (gated to release intent), not on routine `main` work.
 - **Review rises with the ladder.** PRs to `main` (preview) get ordinary review — it's the integration trunk. Promotion to a `release/YYYY` production train (and the GA cut) gets rigorous, unhurried review — that's the project's quality gate. Match your expectations to where the PR is headed.
 - Address review feedback in additional commits rather than force-pushing — easier to review the changes.
 - If CI fails on something unrelated to your change, ping a maintainer.

README.md

@@ -13,7 +13,7 @@
 > Build automation for C#/.NET — the hard-fork successor to NUKE.
 
 [![Docs](https://img.shields.io/badge/docs-docs.fallout.build-blue?logo=readthedocs&logoColor=white)](https://docs.fallout.build/)
-[![CI](https://github.com/Fallout-build/Fallout/actions/workflows/ubuntu-latest.yml/badge.svg)](https://github.com/Fallout-build/Fallout/actions/workflows/ubuntu-latest.yml)
+[![CI](https://github.com/Fallout-build/Fallout/actions/workflows/build.yml/badge.svg)](https://github.com/Fallout-build/Fallout/actions/workflows/build.yml)
 [![NuGet](https://img.shields.io/nuget/v/Fallout.Common?label=Fallout.Common)](https://www.nuget.org/packages/Fallout.Common)
 [![NuGet downloads](https://img.shields.io/nuget/dt/Fallout.Common?label=downloads)](https://www.nuget.org/packages/Fallout.Common)
 [![Latest release](https://img.shields.io/github/v/release/Fallout-build/Fallout?label=release)](https://github.com/Fallout-build/Fallout/releases/latest)
@@ -84,15 +84,14 @@ Fallout (NUKE's successor) brings your build automation to an even level with ev
 
 ## Build Status
 
-CI runs on every PR targeting `main`, `release/*`, or `support/*` across `ubuntu-latest` — the only required status check. After merge, post-merge validation runs on `windows-latest` and `macos-latest`, and a `…-preview` prerelease is published to **GitHub Packages** under the reserved `Fallout.*` prefix from `main`. **Stable** releases fire from `release/YYYY` tags via `.github/workflows/release.yml` (GitHub Packages + GitHub Releases by default; nuget.org opt-in per release). Docs-only PRs are served by a no-op companion workflow (`ubuntu-latest-docs`) so branch protection is satisfied without spending CI minutes on a real build.
+CI runs on every PR targeting `main`, `release/*`, or `support/*` on `build.yml` (Linux) — its `ubuntu-latest` job is the only required status check. Cross-platform Test+Pack (Windows + macOS) is gated to release intent — PRs into `release/*` / `support/*` and `v*` tag pushes — via `build-cross-platform.yml`; it does not run on routine `main` work. A `…-preview` prerelease is published to **GitHub Packages** under the reserved `Fallout.*` prefix on every push to `main`. **Stable** releases fire from `release/YYYY` tags via `.github/workflows/publish-packages-release.yml` (GitHub Packages + GitHub Releases by default; nuget.org opt-in per release). Docs-only PRs are served by a no-op companion workflow (`build-docs`) so branch protection is satisfied without spending CI minutes on a real build.
 
 | Workflow | Status | Trigger |
 |---|---|---|
-| [`ubuntu-latest`](.github/workflows/ubuntu-latest.yml) | [![ubuntu-latest](https://img.shields.io/github/actions/workflow/status/Fallout-build/Fallout/ubuntu-latest.yml?branch=main&label=&logo=ubuntu&logoColor=white&style=flat-square)](https://github.com/Fallout-build/Fallout/actions/workflows/ubuntu-latest.yml) | PR to `main` / `release/*` / `support/*` (code paths) — **required check** |
-| [`windows-latest`](.github/workflows/windows-latest.yml) | [![windows-latest](https://img.shields.io/github/actions/workflow/status/Fallout-build/Fallout/windows-latest.yml?branch=main&label=&logo=windows&logoColor=white&style=flat-square)](https://github.com/Fallout-build/Fallout/actions/workflows/windows-latest.yml) | push to those branches (post-merge validation) |
-| [`macos-latest`](.github/workflows/macos-latest.yml) | [![macos-latest](https://img.shields.io/github/actions/workflow/status/Fallout-build/Fallout/macos-latest.yml?branch=main&label=&logo=apple&logoColor=white&style=flat-square)](https://github.com/Fallout-build/Fallout/actions/workflows/macos-latest.yml) | push to those branches (post-merge validation) |
-| [`preview`](.github/workflows/preview.yml) | [![preview](https://img.shields.io/github/actions/workflow/status/Fallout-build/Fallout/preview.yml?branch=main&label=&logo=githubactions&logoColor=white&style=flat-square)](https://github.com/Fallout-build/Fallout/actions/workflows/preview.yml) | push to `main` → `…-preview` prerelease to GitHub Packages |
-| [`release`](.github/workflows/release.yml) | [![release](https://img.shields.io/github/actions/workflow/status/Fallout-build/Fallout/release.yml?branch=main&label=&logo=nuget&logoColor=white&style=flat-square)](https://github.com/Fallout-build/Fallout/actions/workflows/release.yml) | tag push on `release/YYYY` (stable) or `support/*` (legacy/retired) — nuget.org opt-in |
+| [`build`](.github/workflows/build.yml) | [![build](https://img.shields.io/github/actions/workflow/status/Fallout-build/Fallout/build.yml?branch=main&label=&logo=ubuntu&logoColor=white&style=flat-square)](https://github.com/Fallout-build/Fallout/actions/workflows/build.yml) | PR to `main` / `release/*` / `support/*` (code paths) — job `ubuntu-latest` is the **required check** |
+| [`build-cross-platform`](.github/workflows/build-cross-platform.yml) | [![build-cross-platform](https://img.shields.io/github/actions/workflow/status/Fallout-build/Fallout/build-cross-platform.yml?label=&logo=github&logoColor=white&style=flat-square)](https://github.com/Fallout-build/Fallout/actions/workflows/build-cross-platform.yml) | PR to `release/*` / `support/*` or `v*` tag push — Windows + macOS (release intent) |
+| [`publish-packages-preview`](.github/workflows/publish-packages-preview.yml) | [![publish-packages-preview](https://img.shields.io/github/actions/workflow/status/Fallout-build/Fallout/publish-packages-preview.yml?branch=main&label=&logo=githubactions&logoColor=white&style=flat-square)](https://github.com/Fallout-build/Fallout/actions/workflows/publish-packages-preview.yml) | push to `main` → `…-preview` prerelease to GitHub Packages |
+| [`publish-packages-release`](.github/workflows/publish-packages-release.yml) | [![publish-packages-release](https://img.shields.io/github/actions/workflow/status/Fallout-build/Fallout/publish-packages-release.yml?branch=main&label=&logo=nuget&logoColor=white&style=flat-square)](https://github.com/Fallout-build/Fallout/actions/workflows/publish-packages-release.yml) | tag push on `release/YYYY` (stable) or `support/*` (legacy/retired) — nuget.org opt-in |
 
 Multi-provider CI support (Azure Pipelines, GitLab, TeamCity, AppVeyor) was removed during the takeover and is being revived demand-driven — see [#8](https://github.com/Fallout-build/Fallout/issues/8).