@htekdev/actions-debugger 1.0.14 → 1.0.15

package/errors/caching-artifacts/upload-artifact-v3-retirement-blocked.yml

@@ -0,0 +1,123 @@
+id: caching-artifacts-016
+title: "actions/upload-artifact v3 Automatically Blocked After January 2025 Retirement"
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - download-artifact
+  - v3
+  - deprecated
+  - retirement
+  - brownout
+patterns:
+  - regex: "automatically failed.*deprecated.*version.*upload-artifact"
+    flags: "i"
+  - regex: "This request has been automatically failed because it uses a deprecated version"
+    flags: "i"
+  - regex: "upload-artifact.*v3.*deprecated"
+    flags: "i"
+  - regex: "download-artifact.*v3.*deprecated"
+    flags: "i"
+error_messages:
+  - "This request has been automatically failed because it uses a deprecated version of actions/upload-artifact: v3"
+  - "This request has been automatically failed because it uses a deprecated version of actions/download-artifact: v3"
+root_cause: |
+  GitHub retired **actions/upload-artifact@v3** and **actions/download-artifact@v3**
+  on January 30, 2025. After the retirement date, any workflow still calling v3 of
+  these actions receives an immediate hard failure at the step level — the action
+  does not run; instead, the runner returns:
+
+    "This request has been automatically failed because it uses a deprecated
+     version of actions/upload-artifact: v3"
+
+  **Timeline:**
+  - April 16, 2024 — GitHub announced v3 deprecation and scheduled retirement
+  - November 2024 → January 2025 — Brownout periods (random scheduled failures)
+  - January 30, 2025 — Full retirement: all v3 calls blocked unconditionally
+
+  **Why repos are still affected:**
+  - Many CI configurations were written before the deprecation announcement and
+    were never updated
+  - Reusable workflows called from other orgs/repos may reference v3 internally
+  - Third-party action marketplace actions that internally use v3 as a dependency
+    were broken until their own maintainers upgraded
+  - Workflows with infrequent trigger schedules (e.g., monthly releases) only hit
+    the brownout windows occasionally, masking the problem until full retirement
+
+  Source: GitHub Changelog 2024-04-16, community discussions/149325
+fix: |
+  Upgrade both upload and download steps to v4 simultaneously. Do NOT mix v3 and v4
+  in the same workflow — they use different artifact backends and are not cross-compatible.
+
+  **Key v4 behavior changes to be aware of:**
+  - Artifact names must be unique per workflow run (v4 does NOT overwrite; throws 409)
+  - Hidden files (dotfiles) are excluded by default — set `include-hidden-files: true`
+    if you need them
+  - Cross-repo artifact access requires explicit permissions
+  - GHES instances older than 3.15 do not support v4 — pin to v3 only if on old GHES
+    (but old GHES has its own known issues)
+fix_code:
+  - language: yaml
+    label: "Migrate upload and download to v4 (minimal change)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run build
+
+            # ❌ Retired — will auto-fail after Jan 30, 2025
+            # - uses: actions/upload-artifact@v3
+            #   with:
+            #     name: dist
+            #     path: dist/
+
+            # ✅ Use v4
+            - uses: actions/upload-artifact@v4
+              with:
+                name: dist
+                path: dist/
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            # ✅ Download also on v4 — must match upload version
+            - uses: actions/download-artifact@v4
+              with:
+                name: dist
+                path: dist/
+  - language: yaml
+    label: "Handle v4 duplicate-name conflict if multiple jobs upload the same name"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              target: [linux, windows, macos]
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Build ${{ matrix.target }}" > output.txt
+
+            # v4: artifact names must be unique per run
+            - uses: actions/upload-artifact@v4
+              with:
+                # Append matrix value to keep names unique
+                name: output-${{ matrix.target }}
+                path: output.txt
+prevention:
+  - "Run `grep -r 'upload-artifact@v3\\|download-artifact@v3' .github/` periodically to catch stale version pins."
+  - "Use Dependabot or Renovate to automatically open PRs when GitHub-maintained actions release new major versions."
+  - "Subscribe to the GitHub Changelog (https://github.blog/changelog/) for deprecation notices."
+  - "When upgrading to v4, test artifact names for uniqueness — v4 throws HTTP 409 when the same name is uploaded twice in one run."
+  - "Set `retention-days` explicitly on v4 artifacts; default retention changed between v3 and v4."
+docs:
+  - url: "https://github.blog/changelog/2024-04-16-deprecation-notice-v3-of-the-artifact-actions"
+    label: "GitHub Changelog: Deprecation notice — v3 of the artifact actions"
+  - url: "https://github.com/orgs/community/discussions/149325"
+    label: "Community discussion — workflows failing after artifact v3 retirement"
+  - url: "https://github.com/actions/upload-artifact/blob/main/docs/MIGRATION.md"
+    label: "actions/upload-artifact — v3 to v4 migration guide"
+  - url: "https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts"
+    label: "GitHub Docs: Storing workflow data as artifacts"

package/errors/concurrency-timing/always-cleanup-5min-forced-kill.yml

@@ -0,0 +1,140 @@
+id: concurrency-timing-011
+title: "always() Cleanup Jobs Forcibly Killed After 5-Minute Cancellation Timeout"
+category: concurrency-timing
+severity: warning
+tags:
+  - always
+  - cancellation
+  - cleanup
+  - forced-termination
+  - notification
+  - timeout
+  - teardown
+patterns:
+  - regex: "The runner has received a shutdown signal"
+    flags: "i"
+  - regex: "Job was cancelled"
+    flags: "i"
+  - regex: "The operation was canceled"
+    flags: "i"
+error_messages:
+  - "The runner has received a shutdown signal. This can happen when the runner service is stopped, a new job is started, or the runner is in the process of shutting down."
+  - "Job was cancelled"
+root_cause: |
+  When a workflow run is cancelled (manually or via `cancel-in-progress`), GitHub Actions
+  re-evaluates the `if:` condition for every currently running job. Jobs marked with
+  `if: always()` continue running — this is the intended mechanism for cleanup, notifications,
+  and teardown steps.
+
+  However, GitHub enforces a **5-minute hard termination window** after cancellation is
+  initiated. Once 5 minutes have elapsed since the cancellation signal, ALL remaining jobs
+  are forcibly killed by the server, regardless of their `if:` conditions — including jobs
+  explicitly marked `if: always()`.
+
+  This means:
+  - Cleanup jobs that take more than 5 minutes (Terraform destroy, test result uploads,
+    Slack notifications with retries, database teardown) will be killed mid-execution.
+  - The job may appear partially completed in the logs with no clear failure message —
+    it simply stops, often leaving infrastructure in a partial or inconsistent state.
+  - Developers are surprised that `always()` does not guarantee the job completes after
+    a workflow cancellation.
+
+  Common failure scenarios:
+  - Artifact upload in an `if: always()` post-job step when the upload is slow
+  - Terraform `destroy` as a cleanup job when a long-running deployment is cancelled
+  - Notification jobs that retry on transient failures and consume more time than expected
+  - Integration test teardown (database resets, container removal) that exceeds 5 minutes
+
+  Source: GitHub Docs — Canceling a workflow: "After the 5 minute cancellation timeout
+  period, the server will forcibly terminate all jobs that are still running."
+fix: |
+  Design `always()` cleanup jobs to complete well within 5 minutes. Add a job-level
+  `timeout-minutes: 4` to any cleanup job that runs after cancellation so it fails
+  cleanly rather than being force-killed at an unpredictable point.
+
+  For teardown that cannot be shortened, trigger cleanup from a separate workflow using
+  `workflow_run: [completed]` — it runs after the cancelled run fully settles and is
+  not subject to the 5-minute window.
+
+  Use the `cancelled()` expression to detect cancellation and take a fast code path.
+fix_code:
+  - language: yaml
+    label: "Guard cleanup job with timeout-minutes to fail fast before forced kill"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          timeout-minutes: 60
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+
+        cleanup:
+          needs: deploy
+          if: always()
+          runs-on: ubuntu-latest
+          timeout-minutes: 4   # Stay under the 5-min forced-kill window
+          steps:
+            - name: Teardown infrastructure
+              run: ./teardown.sh
+              timeout-minutes: 3   # Per-step guard too
+
+  - language: yaml
+    label: "Use cancelled() to take a fast notification path on cancellation"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./slow-build.sh
+
+        notify:
+          needs: build
+          if: always()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Quick notification (cancellation — must be fast)
+              if: cancelled()
+              run: |
+                curl -s -X POST "$SLACK_WEBHOOK" \
+                  -H 'Content-type: application/json' \
+                  -d '{"text":"⚠️ Workflow cancelled — cleanup may be incomplete"}'
+
+            - name: Full notification (success or failure path — has time)
+              if: "!cancelled()"
+              run: ./full-notify.sh "${{ needs.build.result }}"
+
+  - language: yaml
+    label: "Post-cancellation teardown via workflow_run — not subject to 5-min window"
+    code: |
+      # cleanup.yml — separate workflow triggered after any completion including cancellation
+      on:
+        workflow_run:
+          workflows: ["Deploy"]
+          types: [completed]
+
+      jobs:
+        teardown:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Emergency cleanup when deploy was cancelled
+              if: github.event.workflow_run.conclusion == 'cancelled'
+              run: ./emergency-teardown.sh
+
+            - name: Normal cleanup on success or failure
+              if: github.event.workflow_run.conclusion != 'cancelled'
+              run: ./standard-teardown.sh
+prevention:
+  - "Keep `if: always()` cleanup jobs under 4 minutes — add `timeout-minutes: 4` as a safety guard."
+  - "Use `if: cancelled()` to detect cancellation and take a fast code path rather than the full teardown path."
+  - "For cleanup that takes longer than 5 minutes, use a separate `workflow_run: [completed]` workflow that runs outside the cancellation window."
+  - "Test cancellation behavior by manually cancelling a long-running workflow and verifying cleanup jobs complete before 5 minutes."
+docs:
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/canceling-a-workflow"
+    label: "GitHub Docs: Canceling a workflow (5-minute forced termination)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#status-check-functions"
+    label: "Status check functions: always(), cancelled()"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "workflow_run event — trigger cleanup after completed workflows"

package/errors/concurrency-timing/concurrency-group-env-context-undefined.yml

@@ -0,0 +1,99 @@
+id: concurrency-timing-010
+title: "env Context Unavailable in Concurrency Group Expression Collapses All Runs"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - env-context
+  - expression
+  - silent-failure
+  - group-collision
+patterns:
+  - regex: "Canceling since a higher priority waiting"
+    flags: "i"
+  - regex: "concurrency.*group.*\"\""
+    flags: "i"
+error_messages:
+  - "Canceling since a higher priority waiting request for '' exists"
+  - "Canceling since a higher priority waiting run was found for ''"
+root_cause: |
+  The `concurrency.group` expression is evaluated at workflow scheduling time, before
+  most runtime contexts are available. The `env` context is one of the contexts that
+  is NOT available when concurrency expressions are evaluated.
+
+  When you use `${{ env.MY_VAR }}` in a concurrency group key:
+  - The expression silently evaluates to an empty string `""`
+  - Every workflow run (across all branches, all events) shares the same group: `""`
+  - Runs from completely unrelated branches cancel each other unexpectedly
+  - The runner may emit "Canceling since a higher priority waiting request for '' exists"
+    with an empty group name — which is the giveaway
+
+  Contexts available in `concurrency.group`: `github`, `inputs`, `vars`
+  Contexts NOT available: `env`, `steps`, `job`, `runner`, `secrets`, `matrix`, `needs`
+
+  This is a documented limitation but easy to miss because the expression evaluates
+  silently without error — it just returns empty string.
+
+  Sources: GitHub Community #26308, #45734, #69704
+fix: |
+  Replace `env` context references in concurrency group expressions with supported
+  contexts. Use `github` (event properties, ref, workflow name), `inputs` (for
+  workflow_dispatch or workflow_call), or `vars` (repository/org variables).
+
+  For environment-specific group keys, use `github.event_name`, `github.ref_name`,
+  `github.workflow`, or pass an explicit input to workflow_dispatch.
+fix_code:
+  - language: yaml
+    label: "Broken — env context evaluates to empty string in concurrency group"
+    code: |
+      # ❌ BROKEN: ${{ env.ENVIRONMENT }} returns "" at scheduling time
+      env:
+        ENVIRONMENT: production
+
+      concurrency:
+        group: deploy-${{ env.ENVIRONMENT }}  # Always evaluates to "deploy-"
+        cancel-in-progress: false
+  - language: yaml
+    label: "Fixed — use github context or vars instead of env"
+    code: |
+      # ✅ FIXED: use github context properties (available at scheduling time)
+      concurrency:
+        group: deploy-${{ github.ref_name }}-${{ github.workflow }}
+        cancel-in-progress: false
+  - language: yaml
+    label: "Fixed — pass environment as workflow_dispatch input for dynamic group key"
+    code: |
+      # ✅ FIXED: expose the value as an input so it's available via `inputs` context
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              required: true
+              type: choice
+              options: [production, staging]
+
+      concurrency:
+        group: deploy-${{ inputs.environment }}
+        cancel-in-progress: false
+  - language: yaml
+    label: "Fixed — use repository variable (vars context is available)"
+    code: |
+      # ✅ FIXED: vars context is available in concurrency expressions
+      concurrency:
+        group: deploy-${{ vars.DEPLOY_ENV }}-${{ github.ref_name }}
+        cancel-in-progress: false
+prevention:
+  - "Only use `github`, `inputs`, and `vars` contexts in `concurrency.group` expressions."
+  - "If you see runs from unrelated branches cancelling each other, inspect the concurrency group key for empty-string evaluation."
+  - "Test concurrency group expressions by adding a step that echoes the group key: `run: echo 'group=${{ github.workflow }}-${{ github.ref_name }}'`."
+  - "If concurrency cancellation messages show an empty group name `''`, the expression evaluated to an empty string."
+  - "Use `vars` (repository/org variables) rather than `env` when you need a configured value in the group key."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency"
+    label: "Using concurrency — supported expression contexts"
+  - url: "https://github.com/orgs/community/discussions/26308"
+    label: "GitHub Community #26308 — env context not available in concurrency"
+  - url: "https://github.com/orgs/community/discussions/69704"
+    label: "GitHub Community #69704 — concurrency group context limitations"
+  - url: "https://github.com/orgs/community/discussions/45734"
+    label: "GitHub Community #45734 — concurrency expression supported contexts"

package/errors/concurrency-timing/required-check-pending-path-filter-skip.yml

@@ -0,0 +1,160 @@
+id: concurrency-timing-013
+title: "Required Status Check Stuck in Pending When Workflow Skipped by Path or Branch Filter"
+category: concurrency-timing
+severity: warning
+tags:
+  - required-status-check
+  - path-filter
+  - branch-filter
+  - pending
+  - pull-request
+  - branch-protection
+  - paths
+  - blocked-pr
+patterns:
+  - regex: "Some checks haven't completed yet|Required status check.*pending"
+    flags: "i"
+  - regex: "Waiting for status:.*pending"
+    flags: "i"
+error_messages:
+  - "Some checks haven't completed yet"
+  - "Required status check is pending"
+  - "Waiting for status: CI / test (pending)"
+root_cause: |
+  GitHub Actions workflows that use `paths:`, `paths-ignore:`, `branches:`, or
+  `branches-ignore:` filters will NOT run — and will NOT report ANY status — for
+  commits that don't match the filter criteria.
+
+  When a required status check is configured in a branch protection rule and the
+  workflow providing that check is skipped by a filter:
+  - The check is NEVER created for that commit — it remains in "Pending" state indefinitely
+  - The PR is blocked from merging with "Some checks haven't completed yet"
+  - The check CANNOT be manually re-triggered without pushing a commit that matches the filter
+
+  Common scenario:
+  A repository has a `ci.yml` workflow with `paths: ['src/**', '*.ts']` and
+  `CI / test` configured as a required status check. A developer opens a PR that only
+  changes `README.md` or `.github/docs/`. The `CI / test` check never runs, shows as
+  "Pending" forever, and the PR is permanently blocked from merging without an admin
+  override or a dummy code commit to trigger the workflow.
+
+  This is explicitly documented behavior but frequently misunderstood:
+  - The workflow appears to work correctly for code-change PRs (the common case)
+  - The bug only surfaces on documentation-only, config-only, or administrative PRs
+  - Developers and reviewers see a pending check with no way to trigger it
+
+  Note: This is distinct from skipped-needs-cascade (job dependency skipping) — this
+  is specifically about the WORKFLOW TRIGGER filter preventing the run from ever starting,
+  so no job status is reported at all.
+
+  Source: GitHub Docs — Troubleshooting required status checks: "If a workflow is skipped
+  due to path filtering, branch filtering or a commit message, then checks associated
+  with that workflow will remain in a 'Pending' state. A pull request that requires those
+  checks to be successful will be blocked from merging."
+fix: |
+  Two main approaches:
+
+  1. **Always-succeeding bypass job** — remove path filters from the workflow trigger,
+     run the workflow for all PRs, use `dorny/paths-filter` or `tj-actions/changed-files`
+     to detect changes inside the workflow, and add a sentinel job that always produces a
+     status. Configure the required check to point at the sentinel job name.
+
+  2. **Split workflow** — keep the path-filtered workflow for actual CI work, and add a
+     separate always-running workflow that provides the required status check name
+     (succeeds immediately for non-code PRs, waits for CI for code PRs).
+fix_code:
+  - language: yaml
+    label: "Fix: always-running workflow with internal path detection and sentinel job"
+    code: |
+      name: CI
+      # No path filter — workflow always runs for all PRs
+      on:
+        pull_request:
+          branches: [main]
+
+      jobs:
+        changes:
+          runs-on: ubuntu-latest
+          outputs:
+            code: ${{ steps.filter.outputs.code }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: dorny/paths-filter@v3
+              id: filter
+              with:
+                filters: |
+                  code:
+                    - 'src/**'
+                    - '*.ts'
+                    - 'package*.json'
+
+        test:
+          needs: changes
+          if: needs.changes.outputs.code == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+
+        # Branch protection required check: "CI / ci-gate" (not "CI / test")
+        # Always produces a status — green for docs PRs, waits for test on code PRs
+        ci-gate:
+          needs: [changes, test]
+          if: always()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Confirm CI passed or code was not changed
+              run: |
+                CODE_CHANGED="${{ needs.changes.outputs.code }}"
+                TEST_RESULT="${{ needs.test.result }}"
+                if [[ "$CODE_CHANGED" == "false" ]]; then
+                  echo "✅ No code changes — CI gate passes automatically"
+                elif [[ "$TEST_RESULT" == "success" ]]; then
+                  echo "✅ Tests passed"
+                else
+                  echo "❌ Tests $TEST_RESULT"
+                  exit 1
+                fi
+
+  - language: yaml
+    label: "Alternative: run all steps always but skip expensive ones via filter"
+    code: |
+      name: CI
+      on:
+        pull_request:
+          branches: [main]
+      # No workflow-level path filter — status always reported
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: dorny/paths-filter@v3
+              id: filter
+              with:
+                filters: |
+                  code: ['src/**', '*.ts', 'package*.json']
+
+            - name: Install dependencies
+              if: steps.filter.outputs.code == 'true'
+              run: npm ci
+
+            - name: Run tests
+              if: steps.filter.outputs.code == 'true'
+              run: npm test
+            # Job always completes with success — check is always reported
+prevention:
+  - "Never use workflow-level `paths:` or `branches:` filters as the sole trigger for a required status check."
+  - "Use `dorny/paths-filter` or `tj-actions/changed-files` INSIDE an always-running workflow instead of workflow-level path filters."
+  - "Name required status checks after jobs that always produce a status, even on non-code PRs."
+  - "Test branch protection rules by opening a documentation-only PR to verify all required checks complete."
+  - "Consider admin overrides as a last resort, not a workflow fix — the root cause will keep happening."
+docs:
+  - url: "https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks"
+    label: "Troubleshooting required status checks (path filter skip documented)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore"
+    label: "Workflow syntax: paths and paths-ignore filters"
+  - url: "https://github.com/dorny/paths-filter"
+    label: "dorny/paths-filter — detect changed files inside workflow"

package/errors/concurrency-timing/wait-timer-cancel-in-progress-starvation.yml

@@ -0,0 +1,125 @@
+id: concurrency-timing-012
+title: "Deployment wait-timer + cancel-in-progress: true Creates Permanent Deployment Starvation Loop"
+category: concurrency-timing
+severity: warning
+tags:
+  - wait-timer
+  - cancel-in-progress
+  - deployment
+  - environment
+  - starvation
+  - concurrency
+  - production
+patterns:
+  - regex: "Run was cancelled|Canceling since a higher priority waiting request"
+    flags: "i"
+  - regex: "wait.?timer|waiting for environment.*approval"
+    flags: "i"
+error_messages:
+  - "Run was cancelled"
+  - "Canceling since a higher priority waiting request for 'production' exists"
+root_cause: |
+  When a deployment workflow combines `concurrency.cancel-in-progress: true` with a
+  deployment environment that has a `wait-timer` configured (a mandatory delay before
+  deployment proceeds), every new commit to the branch creates a starvation loop where
+  no deployment ever reaches the execution phase:
+
+  1. Run A starts → deployment job begins waiting out the environment wait-timer (e.g., 5 min)
+  2. A new commit is pushed → Run B starts in the same concurrency group
+  3. `cancel-in-progress: true` fires → Run A is cancelled while still in the wait-timer
+  4. Run B now begins its own wait-timer countdown
+  5. Another commit arrives → Run B is cancelled during its timer
+  6. This repeats indefinitely — no deployment ever executes
+
+  This loop is particularly insidious because:
+  - All cancellations appear expected and benign in the Actions UI (no failures shown)
+  - The repository looks healthy — CI passes, deployments start — but production is
+    silently never updated
+  - Active development repos where commits arrive faster than the wait-timer duration
+    are especially vulnerable
+
+  Note: GitHub's concurrency model allows only ONE pending run per group. With
+  `cancel-in-progress: true`, a new run cancels the RUNNING run (not just queues) —
+  so even a very short wait-timer cannot escape this if commits arrive frequently.
+fix: |
+  Do not combine `cancel-in-progress: true` with deployment environment `wait-timer`
+  on the same workflow. Use `cancel-in-progress: false` (the default) for deploy
+  workflows — this queues runs so each commit eventually deploys in order.
+
+  If you want fast feedback for CI but reliable deployments for CD, split them into
+  separate workflow files with different concurrency strategies.
+fix_code:
+  - language: yaml
+    label: "Fix: disable cancel-in-progress for deploy workflow with wait-timer"
+    code: |
+      name: Deploy to Production
+      on:
+        push:
+          branches: [main]
+
+      concurrency:
+        group: deploy-production
+        cancel-in-progress: false  # Queue — never starve a deployment with wait-timer
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: production   # Has wait-timer: 5 configured
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+
+  - language: yaml
+    label: "Split pipeline: CI cancels freely; deploy queues safely after CI"
+    code: |
+      # ci.yml — fast feedback, cancel stale runs is fine
+      name: CI
+      on:
+        push:
+          branches: [main]
+      concurrency:
+        group: ci-${{ github.ref }}
+        cancel-in-progress: true   # OK: no side effects
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+
+      ---
+      # deploy.yml — triggered after CI, environment has wait-timer
+      name: Deploy
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+          branches: [main]
+
+      concurrency:
+        group: deploy-production
+        cancel-in-progress: false   # Queue; every successful CI run gets deployed
+
+      jobs:
+        deploy:
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          runs-on: ubuntu-latest
+          environment: production   # wait-timer is safe — no cancel-in-progress racing it
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.workflow_run.head_sha }}
+            - run: ./deploy.sh
+prevention:
+  - "Never combine `cancel-in-progress: true` with a deployment environment `wait-timer` in the same workflow."
+  - "Use `cancel-in-progress: false` for any workflow that deploys to environments with protection rules."
+  - "Decouple CI (cancel-ok, fast) from CD (queued, reliable) into separate workflow files."
+  - "Monitor the Actions tab for a pattern of all deployments showing as CANCELLED — this is a sign of starvation."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency"
+    label: "GitHub Docs: Using concurrency in GitHub Actions"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment#wait-timer"
+    label: "GitHub Docs: Managing environments — wait timer"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "workflow_run event — decouple CI and CD pipelines"