fix(ci): replace PR promotion with squash push in promote-to-lts (#1177)

## Problem

The `promote-to-lts.yml` workflow has caused repeated git tree pollution
on `lts`. After digging through the full history, here is the root cause
chain:

1. **Circular history reference**: `ffa30fe` (`Merge branch 'lts' into
main`) accidentally merged `lts` → `main`, embedding lts's pull-bot
merge commits inside main's graph.
2. **lts has diverged**: 4 commits exist in `lts` that aren't in `main`
(old pull-bot merges + the `2a780d2` emergency CI sync).
3. **Default merge commit strategy**: The previous `gh pr create --head
main` approach created a PR that, when merged with GitHub's default
button, produced a merge commit with two parents. That commit dragged
main's full cross-contaminated history into `lts` on every promotion,
deepening the diamond graph each time.
4. **No pre-flight guard**: Nothing prevented the workflow from running
when `lts` was already in a diverged state.

## Solution

Replace the PR creation step with a direct **squash push**:

1. **Pre-flight check** — `git rev-list origin/lts ^origin/main
--count`. If > 0, fail immediately and list the divergent commits with
instructions to land them in `main` first.
2. **`git merge --squash origin/main`** — collapses all pending main
changes into a single staged changeset. No merge commit. No embedded
history.
3. **One clean commit** pushed to `lts` per promotion event → linear
history.

The `workflow_dispatch` trigger is the human approval gate — a
maintainer must explicitly trigger the workflow to promote.

## Why not keep the PR?

Previous attempts:
| Approach | Why it failed |
|---|---|
| Old Pull bot | Created `[pull]` merge commits; also ran in reverse |
| Intermediate branch + PR | Merge commit still polluted `lts` on merge
|
| `gh pr create --head main` (last fix) | PR merged with default
strategy = merge commit |
| Direct file sync `2a780d2` | Added lts-unique commits, deepening
divergence |

A squash push is deterministic — the workflow controls the merge
strategy, not the human clicking the merge button.

## Changes

- `.github/workflows/promote-to-lts.yml`: Replace `gh pr create` with
checkout + pre-flight + squash merge + push. Swap `pull-requests: write`
→ `contents: write`.
- `AGENTS.md`: Update promotion flow description; add **NEVER commit
directly to `lts`** rule.

## ⚠️ Current state of lts

`lts` currently has 4 commits not in `main`. The pre-flight check will
**correctly block** the next promotion and print those commits.
Resolution: the CI fixes from `2a780d2` are already in `main` as
`6ec7dd5` — once the divergent commits are resolved and `git rev-list
origin/lts ^origin/main` is empty, promotion will work cleanly.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: castrojo

.github/workflows/promote-to-lts.yml

@@ -3,35 +3,69 @@ name: Promote Main to LTS
 on:
   workflow_dispatch:
     inputs:
-      pr_title:
-        description: 'Pull request title'
+      commit_title:
+        description: 'Commit title for the squash promotion commit'
         required: false
-        default: 'Promote main to lts'
-      pr_body:
-        description: 'Pull request body'
+        default: 'promote: main to lts'
+      commit_body:
+        description: 'Commit body (optional)'
         required: false
         default: |
-          ## Summary
-          Promotion of tested changes from `main` to `lts` production branch.
-          
-          **IMPORTANT**: This PR should ONLY contain commits from `main` → `lts`. Never merge in the opposite direction.
+          Squash promotion of tested changes from `main` to `lts`.
 
 permissions:
-  pull-requests: write
-  issues: write
+  contents: write
 
 jobs:
-  create-promotion-pr:
+  promote:
     runs-on: ubuntu-latest
     steps:
-      - name: Create Pull Request
-        env:
-          GH_TOKEN: ${{ github.token }}
+      - name: Checkout lts
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: lts
+          fetch-depth: 0
+          token: ${{ github.token }}
+
+      - name: Fetch main
+        run: git fetch origin main
+
+      - name: Pre-flight check
         run: |
-          gh pr create \
-            --repo ${{ github.repository }} \
-            --base lts \
-            --head main \
-            --title "${{ inputs.pr_title }}" \
-            --body "${{ inputs.pr_body }}" \
-            --label "promotion"
+          UNIQUE=$(git rev-list origin/lts ^origin/main --count)
+          if [ "$UNIQUE" -gt 0 ]; then
+            echo "ERROR: lts has $UNIQUE commit(s) that are not in main:"
+            git log --oneline origin/lts ^origin/main
+            echo ""
+            echo "All changes must land in main before promoting to lts."
+            echo "Land the above commits in main first, then re-run this workflow."
+            exit 1
+          fi
+          echo "Pre-flight passed: lts has no commits outside of main."
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Squash merge main into lts
+        id: squash
+        run: |
+          git merge --squash origin/main
+          if git diff --cached --quiet; then
+            echo "No changes to promote: origin/main is already fully merged into lts."
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit promotion
+        if: steps.squash.outputs.has_changes == 'true'
+        run: |
+          git commit \
+            -m "${{ inputs.commit_title }}" \
+            -m "${{ inputs.commit_body }}"
+
+      - name: Push to lts
+        if: steps.squash.outputs.has_changes == 'true'
+        run: git push origin lts

AGENTS.md

@@ -121,7 +121,7 @@ This section is the authoritative reference for all CI/CD behavior. Read it comp
 | `build-dx-hwe.yml` | Caller — builds `bluefin-dx` with HWE kernel |
 | `reusable-build-image.yml` | Reusable workflow — all 5 callers invoke this |
 | `scheduled-lts-release.yml` | Dispatcher — owns the weekly Sunday production release |
-| `promote-to-lts.yml` | Creates a PR to merge `main` → `lts` (see below) |
+| `promote-to-lts.yml` | Squash-pushes `main` → `lts` with pre-flight divergence check (see below) |
 | `generate-release.yml` | Creates a GitHub Release when `build-gdx.yml` completes on `lts` |
 
 ### Two Branches, Two Tag Namespaces
@@ -139,9 +139,9 @@ Promotion and production release are **intentionally decoupled**. There are two
 
 **Phase 1 — Promotion (manual, no publishing):**
 1. A maintainer triggers `promote-to-lts.yml` via `workflow_dispatch`
-2. The workflow opens a PR from `main` targeting `lts` directly (no intermediate branch)
-3. A maintainer reviews and merges the PR
-4. The merge triggers a `push` event on `lts` — all 5 build workflows run as **validation builds** (`publish=false`). No images are published. This is intentional: it confirms that the merged code builds cleanly on `lts` before the next production release.
+2. The workflow runs a **pre-flight check**: fails immediately if `lts` has any commits not reachable from `main`, printing those commits with instructions to land them in `main` first.
+3. The workflow performs a **squash merge** (`git merge --squash origin/main`) and pushes one clean commit to `lts`. There is no PR. Triggering `workflow_dispatch` is the human approval step.
+4. The push triggers a `push` event on `lts` — all 5 build workflows run as **validation builds** (`publish=false`). No images are published. This confirms the promoted code builds cleanly on `lts` before the next production release.
 
 **Phase 2 — Production release (automated or manual publishing):**
 1. `scheduled-lts-release.yml` fires at `0 2 * * 0` (Sunday 2am UTC), OR a maintainer manually triggers it
@@ -153,6 +153,8 @@ Promotion and production release are **intentionally decoupled**. There are two
 
 **NEVER merge `lts` into `main`.** The flow is always one-way: `main` → `lts`.
 
+**NEVER commit directly to `lts`.** All changes — including CI hotfixes — must land in `main` first. Direct commits to `lts` create divergence that causes the pre-flight check to fail and blocks future promotions.
+
 ### `publish` Input — How It Is Evaluated
 
 All 5 caller workflows pass the same `publish:` expression:
@@ -263,7 +265,7 @@ If you see `schedule:` in any of the 5 build callers, remove it entirely. Do not
 - `build-regular-hwe.yml` — HWE kernel variant of `bluefin`
 - `build-dx-hwe.yml` — HWE kernel variant of `bluefin-dx`
 - `scheduled-lts-release.yml` — Weekly production release dispatcher (sole owner of Sunday builds)
-- `promote-to-lts.yml` — Opens a one-way `main` → `lts` promotion PR
+- `promote-to-lts.yml` — Squash-pushes `main` into `lts` (with pre-flight divergence check)
 - `generate-release.yml` — Creates GitHub Release after successful GDX build on `lts`
 
 ## Validation Scenarios