@htekdev/actions-debugger 1.0.10 → 1.0.12

package/errors/caching-artifacts/cache-cross-os-archive-missing.yml

@@ -0,0 +1,120 @@
+id: caching-artifacts-013
+title: "Cross-OS Cache Miss — enableCrossOsArchive Not Set"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - cross-os
+  - windows
+  - linux
+  - cache-miss
+  - enableCrossOsArchive
+patterns:
+  - regex: "Cache not found for input keys"
+    flags: "i"
+  - regex: "enableCrossOsArchive.*false"
+    flags: "i"
+  - regex: "cache miss.*windows"
+    flags: "i"
+  - regex: "tar.*posix.*failed"
+    flags: "i"
+error_messages:
+  - "Cache not found for input keys: <key>"
+  - "enableCrossOsArchive: false"
+  - "Cache saved successfully"
+  - "Post job cleanup."
+root_cause: |
+  `actions/cache` uses different archive formats depending on the runner OS:
+  - Linux/macOS: GNU tar (gnutar) with zstd compression
+  - Windows: BSD tar bundled with Git for Windows (`C:\Program Files\Git\usr\bin\tar.exe`)
+
+  When a cache is created on Linux or macOS, the archive is in GNU tar format. When
+  Windows attempts to restore it (or vice versa), the different tar implementation
+  fails to decompress the archive, resulting in a silent cache miss.
+
+  The `enableCrossOsArchive` option (default: `false`) controls whether the cache is
+  stored in a cross-platform-compatible format. Setting it to `true` forces GNU tar
+  format on all platforms, enabling cache sharing across OSes.
+
+  This is particularly common in monorepos where:
+  - Node modules or package caches are written by a Linux job and expected to be
+    restored by a Windows job in the same workflow run
+  - A "seed cache" job runs on Linux and downstream jobs run on Windows
+  - The matrix includes multiple OS values sharing the same cache key
+
+  Tracked in actions/cache#1275 (Cache miss on Windows despite a successful
+  cache-write) — confirmed fixed by setting `enableCrossOsArchive: true`.
+fix: |
+  Add `enableCrossOsArchive: true` to ALL cache steps (both the write and the restore
+  steps) that need to share caches across different OS runners.
+
+  IMPORTANT: The option must be set consistently on both the writing and reading jobs.
+  Setting it only on one side will not work.
+
+  If true cross-OS caching is not needed, ensure each OS creates its own native cache
+  by including `${{ runner.os }}` in the cache key.
+fix_code:
+  - language: yaml
+    label: "Enable cross-OS archive on cache steps that share between Linux and Windows"
+    code: |
+      - name: Cache node modules (cross-OS compatible)
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: node-${{ hashFiles('**/package-lock.json') }}
+          enableCrossOsArchive: true   # Required for Linux↔Windows cache sharing
+
+  - language: yaml
+    label: "OS-specific cache keys (alternative — each OS gets its own cache)"
+    code: |
+      - name: Cache dependencies (OS-scoped key — no cross-OS needed)
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          # Include runner.os so each OS writes its own cache entry
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+  - language: yaml
+    label: "Matrix workflow with consistent enableCrossOsArchive on all jobs"
+    code: |
+      jobs:
+        seed-cache:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Seed shared cache
+              uses: actions/cache@v4
+              with:
+                path: node_modules
+                key: node-${{ hashFiles('**/package-lock.json') }}
+                enableCrossOsArchive: true
+
+        build:
+          needs: seed-cache
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Restore shared cache
+              uses: actions/cache@v4
+              with:
+                path: node_modules
+                key: node-${{ hashFiles('**/package-lock.json') }}
+                enableCrossOsArchive: true   # Must match the write job
+
+prevention:
+  - "Always include `runner.os` in your cache key unless you explicitly need cross-OS sharing."
+  - "When cross-OS sharing IS required, set `enableCrossOsArchive: true` on every step that reads or writes the shared cache."
+  - "Treat cross-OS cache sharing as an explicit opt-in, not the default."
+  - "Test cache restoration on all target OSes during initial workflow setup."
+docs:
+  - url: "https://github.com/actions/cache/blob/main/README.md"
+    label: "actions/cache README: enableCrossOsArchive option"
+  - url: "https://github.com/actions/cache/blob/main/tips-and-workarounds.md"
+    label: "actions/cache: Tips and workarounds (cross-OS section)"
+  - url: "https://github.com/actions/cache/issues/1275"
+    label: "actions/cache#1275: Cache miss on Windows despite a successful cache-write"

package/errors/known-unsolved/matrix-outputs-last-writer-wins.yml

@@ -0,0 +1,137 @@
+id: known-unsolved-011
+title: "Matrix Job Outputs Are Non-Deterministic — Only Last Completed Job's Value Is Used"
+category: known-unsolved
+severity: silent-failure
+tags:
+  - matrix
+  - outputs
+  - non-deterministic
+  - race-condition
+  - jobs-outputs
+  - strategy
+patterns:
+  - regex: "jobs\\.\\w+\\.outputs\\.\\w+"
+    flags: "i"
+  - regex: "matrix.*output.*overwrite"
+    flags: "i"
+  - regex: "only.*last.*matrix.*job.*output"
+    flags: "i"
+error_messages:
+  - "outputs from matrix returns only the last value"
+  - "matrix job output overwritten by later-completing job"
+root_cause: |
+  GitHub Actions does not support aggregating outputs across matrix jobs. When a job uses
+  `strategy: matrix:` and defines `outputs:`, all matrix instances write to the SAME
+  output key. The value that survives is whichever matrix job completes LAST — and
+  completion order is non-deterministic.
+
+  Example: a 3-element matrix writing `result` as an output. Job [A, B, C] may complete
+  in any order — the downstream job receives only the output from whichever finished last.
+  This can silently produce wrong results that vary between runs.
+
+  The underlying limitation: `jobs.<job_id>.outputs` maps to a single scalar value
+  per key, with no way to collect values from all matrix instances into a structured
+  result. The runner simply last-writes-wins with no conflict detection.
+
+  This is a long-standing limitation tracked in actions/runner#1835 (opened April 2022)
+  and actions/runner#2477. A partial improvement in runner v2.303.0 added `$matrix`
+  context to outputs expressions, but it is still not generally available and has known
+  bugs (runner#2499: workflow won't start with the new syntax on older runners).
+
+  Source: actions/runner#1835 (Outputs from matrix returns only the last value)
+  Source: Stack Overflow #70287603 (Dynamic outputs for job with strategy.matrix)
+fix: |
+  There is no native GitHub Actions solution for collecting all matrix job outputs into
+  a structured result. Use one of these workarounds:
+
+  Workaround 1 — Write to artifacts, aggregate downstream:
+    Each matrix job writes its result to a uniquely-named artifact file. A downstream
+    aggregator job downloads all artifacts and processes them.
+
+  Workaround 2 — Encode outputs in artifact JSON, then use as dynamic matrix:
+    Popularized by the `matrix-output` marketplace action. Each job appends a JSON row
+    to an artifact, and a reporting job downloads and merges them.
+
+  Workaround 3 — Use reusable workflows with known job indices:
+    Reusable workflows allow accessing specific job outputs via the caller's
+    `jobs.<reusable_workflow_job>.outputs` context.
+
+  Workaround 4 — Consolidate into a single non-matrix job:
+    If the matrix outputs must be consumed, consider restructuring to run the work
+    sequentially in one job or use a scripted loop.
+fix_code:
+  - language: yaml
+    label: "Workaround: write output to artifact file, aggregate in downstream job"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              component: [api, web, worker]
+          runs-on: ubuntu-latest
+          steps:
+            - name: Build component
+              run: |
+                # ... build logic ...
+                echo "build_status=success" >> result-${{ matrix.component }}.txt
+
+            - name: Upload result artifact
+              uses: actions/upload-artifact@v4
+              with:
+                name: result-${{ matrix.component }}
+                path: result-${{ matrix.component }}.txt
+
+        aggregate:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download all results
+              uses: actions/download-artifact@v4
+              with:
+                pattern: result-*
+                merge-multiple: true
+
+            - name: Aggregate results
+              run: |
+                for f in result-*.txt; do
+                  echo "=== $f ==="
+                  cat "$f"
+                done
+
+  - language: yaml
+    label: "Anti-pattern: matrix outputs — only one value survives (last writer wins)"
+    code: |
+      # ❌ WRONG — only last-completing job's output is used by downstream-job
+      jobs:
+        build:
+          strategy:
+            matrix:
+              component: [api, web, worker]
+          runs-on: ubuntu-latest
+          outputs:
+            status: ${{ steps.build.outputs.status }}   # ← non-deterministic!
+          steps:
+            - id: build
+              run: echo "status=done-${{ matrix.component }}" >> $GITHUB_OUTPUT
+
+        downstream-job:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "${{ needs.build.outputs.status }}"
+            # Prints ONE value (whichever matrix job finished last) — unpredictable
+
+prevention:
+  - "Never rely on matrix job outputs for per-job values — outputs are not aggregated."
+  - "Use upload-artifact/download-artifact with unique names per matrix dimension to collect per-job results."
+  - "If a downstream job needs all matrix results, prefer artifact-based aggregation over job outputs."
+  - "Document in your workflow comments that matrix outputs are single-valued and non-deterministic."
+docs:
+  - url: "https://github.com/actions/runner/issues/1835"
+    label: "actions/runner#1835: Outputs from matrix returns only the last value"
+  - url: "https://stackoverflow.com/questions/70287603/dynamic-outputs-for-job-with-strategy-matrix"
+    label: "Stack Overflow: Dynamic outputs for job with strategy.matrix"
+  - url: "https://github.com/marketplace/actions/matrix-output"
+    label: "Marketplace: matrix-output action (artifact-based aggregation workaround)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "GitHub Docs: Passing information between jobs"

package/errors/known-unsolved/uses-key-no-expression-support.yml

@@ -0,0 +1,134 @@
+id: known-unsolved-012
+title: "uses: Key Does Not Support Expressions or Context Variables — Must Be a Static String"
+category: known-unsolved
+severity: error
+tags:
+  - uses
+  - expression
+  - context
+  - dynamic-action
+  - composite
+  - local-action
+patterns:
+  - regex: "uses:\\s*\\.?/\\$\\{\\{"
+    flags: "i"
+  - regex: "uses:\\s*['\"]?\\$\\{\\{"
+    flags: "i"
+  - regex: "Unrecognized named-value.*uses"
+    flags: "i"
+  - regex: "Invalid workflow file.*uses.*expression"
+    flags: "i"
+error_messages:
+  - "Invalid workflow file: .github/workflows/ci.yml — uses: does not support expression syntax"
+  - "The 'uses' field must be a literal string and cannot contain expressions"
+  - "Unrecognized named-value: 'env' at position 1 within expression in uses:"
+root_cause: |
+  GitHub Actions resolves all `uses:` references (actions and reusable workflows) BEFORE
+  the job starts executing — at workflow evaluation / job queue time. At that point,
+  no runtime contexts (env, inputs, github, matrix, steps, needs) are available.
+
+  As a result, you cannot use `${{ }}` expression syntax in a `uses:` key at any level:
+    - Step-level: `uses: ${{ env.MY_ACTION }}@${{ env.VERSION }}` ❌
+    - Local path with variable: `uses: ./${{ env.DIR }}/my-action` ❌
+    - Dynamic version pin: `uses: actions/setup-node@${{ inputs.node-version }}` ❌
+    - Reusable workflow: `uses: ${{ github.repository }}/.github/workflows/ci.yml@main` ❌
+
+  This is an architectural constraint: the runner must download and validate actions
+  (and reusable workflows) before any step code can run. Allowing runtime expressions
+  would break policy enforcement (org-level allowed-actions lists) and make workflow
+  graphs non-deterministic at parse time.
+
+  Note: `env:` and `with:` inputs to an action DO support expressions — only the `uses:`
+  key itself is restricted.
+
+  Source: actions/runner#1479 (Support context/matrix variables in steps of type 'uses')
+  Source: actions/runner#895 (Allow expressions in uses:)
+  Source: Stack Overflow #75373413 (Reference a variable in uses when pointing to a path)
+fix: |
+  There is no native GitHub Actions solution for dynamic `uses:` values.
+
+  Option 1 — Hard-code the version or path (recommended for most cases):
+    Pin versions explicitly in the workflow file. Use Dependabot or Renovate to keep
+    action versions updated automatically.
+
+  Option 2 — Use a composite action or script as a dispatcher:
+    Create a wrapper composite action that accepts an input and uses `if:` conditions
+    to call different static actions based on the input value.
+
+  Option 3 — Use step-security/dynamic-uses (third-party workaround):
+    The `dynamic-uses` action by step-security resolves and invokes actions dynamically
+    at runtime. This works around the limitation but adds a third-party dependency.
+
+  Option 4 — Restructure to not need dynamic action references:
+    If you're trying to select between local action paths, check out the repo first and
+    use a scripted approach instead of composite action dispatch.
+fix_code:
+  - language: yaml
+    label: "Anti-pattern — expressions in uses: cause parse error"
+    code: |
+      # ❌ WRONG — none of these are supported
+      steps:
+        - uses: ./${{ env.ACTION_DIR }}/my-action         # ← parse error
+        - uses: actions/setup-node@${{ inputs.version }}  # ← parse error
+        - uses: ${{ github.repository }}/.github/workflows/deploy.yml@main  # ← error
+
+  - language: yaml
+    label: "Fix: hard-code the version, use Dependabot to keep it updated"
+    code: |
+      # ✅ CORRECT — static string in uses:
+      steps:
+        - uses: actions/setup-node@v4          # pin to major version
+        - uses: actions/setup-node@11.0.0      # or exact version
+        - uses: ./.github/actions/my-action    # local action: always relative to repo root
+
+      # Keep versions current with Dependabot (.github/dependabot.yml):
+      # version: 2
+      # updates:
+      #   - package-ecosystem: "github-actions"
+      #     directory: "/"
+      #     schedule:
+      #       interval: "weekly"
+
+  - language: yaml
+    label: "Workaround: if-based dispatch when choosing between known static actions"
+    code: |
+      # ✅ Conditional dispatch using if: conditions on static uses:
+      steps:
+        - name: Setup Node (version from input)
+          uses: actions/setup-node@v4
+          with:
+            node-version: ${{ inputs.node-version }}   # ← with: supports expressions
+
+        # If you truly need different actions based on input:
+        - name: Use action for staging
+          if: inputs.environment == 'staging'
+          uses: ./actions/deploy-staging              # static path
+
+        - name: Use action for production
+          if: inputs.environment == 'production'
+          uses: ./actions/deploy-production           # static path
+
+  - language: yaml
+    label: "Workaround: step-security/dynamic-uses third-party action"
+    code: |
+      # Third-party workaround — resolves expressions in uses: at runtime
+      steps:
+        - uses: step-security/dynamic-uses@v1
+          with:
+            uses: actions/setup-node@${{ inputs.node-version }}
+            with: '{ "node-version": 18 }'
+
+prevention:
+  - "Always use static literal strings in `uses:` keys — no `${{ }}` expressions."
+  - "Use `with:` inputs (which DO support expressions) to pass dynamic values to actions."
+  - "Use Dependabot or Renovate to automate action version bumps so manual pinning stays current."
+  - "For environment-specific action selection, use `if:` conditions on separate steps with static `uses:` values."
+docs:
+  - url: "https://github.com/actions/runner/issues/1479"
+    label: "actions/runner#1479: Support context/matrix variables in steps of type 'uses'"
+  - url: "https://github.com/actions/runner/issues/895"
+    label: "actions/runner#895: Allow expressions in uses: key"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-pre-written-building-blocks-in-your-workflow"
+    label: "GitHub Docs: Using pre-written building blocks (actions)"
+  - url: "https://github.com/step-security/dynamic-uses"
+    label: "step-security/dynamic-uses: third-party workaround for dynamic uses:"

package/errors/runner-environment/checkout-persist-credentials-false-git-auth.yml

@@ -0,0 +1,124 @@
+id: runner-environment-032
+title: "persist-credentials: false Breaks Subsequent Git Push / Authentication"
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - persist-credentials
+  - git-push
+  - authentication
+  - credential-helper
+  - git-auto-commit
+patterns:
+  - regex: "fatal:.*could not read Username.*No such device"
+    flags: "i"
+  - regex: "fatal: Authentication failed for.*github\\.com"
+    flags: "i"
+  - regex: "remote:.*Invalid username or password"
+    flags: "i"
+  - regex: "persist-credentials.*false"
+    flags: "i"
+  - regex: "error: The requested URL returned error: 403"
+    flags: "i"
+error_messages:
+  - "fatal: could not read Username for 'https://github.com': No such device or address"
+  - "fatal: Authentication failed for 'https://github.com/owner/repo.git/'"
+  - "remote: Invalid username or password."
+  - "error: The requested URL returned error: 403"
+  - "remote: Support for password authentication was removed"
+root_cause: |
+  When `actions/checkout` runs with `persist-credentials: false`, it:
+  1. Checks out the repository
+  2. Explicitly **removes** the git credential helper that was configured for GITHUB_TOKEN auth
+  3. Leaves the working directory with no way to authenticate subsequent git operations
+
+  Any `git push`, `git pull`, or `git fetch` call that runs AFTER this checkout will
+  fail with an authentication error because there is no credential helper configured.
+
+  This pattern is often introduced deliberately for security (to avoid GITHUB_TOKEN
+  persistence), but developers forget that it also breaks any action or step that needs
+  to push changes back to the repository — such as:
+  - `stefanzweifel/git-auto-commit-action` (fails with "could not read Username")
+  - Manual `git push origin HEAD` steps
+  - Semantic-release, release-please, and other auto-committing tools
+  - Actions that amend, tag, or push version bumps
+
+  The issue is also triggered transitively: if a composite action internally calls
+  `actions/checkout` with `persist-credentials: false`, the credential helper is
+  removed from the runner's git config, breaking git auth for all subsequent steps.
+
+  Tracked across multiple issues: stefanzweifel/git-auto-commit-action#356,
+  stefanzweifel/git-auto-commit-action#397, anthropics/claude-code-action#1236.
+fix: |
+  **Option 1 (simplest): Remove persist-credentials: false**
+  If you set it out of habit or from a template, just remove it. GITHUB_TOKEN credentials
+  stored by actions/checkout are scoped to the runner and do not persist beyond the
+  workflow run anyway.
+
+  **Option 2: Re-configure credentials after checkout**
+  If you need `persist-credentials: false` for security reasons (e.g., to prevent
+  GITHUB_TOKEN from being used by untrusted code), re-add credentials only for the
+  steps that need to push.
+
+  **Option 3: Use SSH instead of HTTPS**
+  Configure SSH deploy keys and use an SSH remote URL to avoid HTTPS credential
+  issues entirely.
+fix_code:
+  - language: yaml
+    label: "Remove persist-credentials: false (simplest fix)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          # REMOVE this line — credentials are scoped to the runner by default
+          # persist-credentials: false
+
+      - name: Commit and push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .
+          git commit -m "chore: auto-update generated files [skip ci]"
+          git push
+
+  - language: yaml
+    label: "Re-configure credentials after persist-credentials: false (security-first workflows)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false   # Untrusted code runs between here and push
+
+      # ... run untrusted/third-party code here ...
+
+      - name: Re-configure GITHUB_TOKEN for push
+        run: |
+          git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+        # Now git push will work again
+
+      - name: Push changes
+        run: git push
+
+  - language: yaml
+    label: "Use PAT or app token to push (avoids GITHUB_TOKEN limitations)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.MY_PAT }}   # Use a PAT that has write access
+          persist-credentials: true     # Default: true — keep this to allow push
+
+      - name: Push changes
+        run: git push
+
+prevention:
+  - "Do not add `persist-credentials: false` unless you have a specific security reason (e.g., running untrusted fork code)."
+  - "If any step after `actions/checkout` needs to push commits or tags, ensure credentials are persisted or re-configured."
+  - "When using `git-auto-commit-action` or similar, check upstream docs for compatibility with `persist-credentials: false`."
+  - "Prefer `token: ${{ secrets.GITHUB_TOKEN }}` with `persist-credentials: true` over re-configuring remote URLs manually."
+docs:
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout: persist-credentials input"
+  - url: "https://github.com/stefanzweifel/git-auto-commit-action/discussions/356"
+    label: "git-auto-commit-action#356: persist-credentials: false compatibility"
+  - url: "https://github.com/stefanzweifel/git-auto-commit-action/issues/397"
+    label: "git-auto-commit-action#397: fatal: could not read Username (checkout v5)"
+  - url: "https://github.com/anthropics/claude-code-action/issues/1236"
+    label: "claude-code-action#1236: fails when persist-credentials: false"

package/errors/runner-environment/windows-default-shell-powershell-not-bash.yml

@@ -0,0 +1,137 @@
+id: runner-environment-033
+title: "Windows Runner Default Shell Is PowerShell — Bash Scripts Silently Fail Without shell: bash"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - shell
+  - bash
+  - powershell
+  - default-shell
+  - run-step
+  - cross-platform
+patterns:
+  - regex: "shell:\\s*C:\\\\Windows\\\\system32\\\\bash\\.EXE"
+    flags: "i"
+  - regex: "The term '.*' is not recognized.*cmdlet.*function.*script"
+    flags: "i"
+  - regex: "pwsh.*noprofile.*noninteractive.*command"
+    flags: "i"
+  - regex: "bash.*error.*not.*recognized.*windows"
+    flags: "i"
+error_messages:
+  - "The term 'set' is not recognized as the name of a cmdlet, function, script file"
+  - "Unrecognized token '||' in pipeline"
+  - "shell: C:\\Windows\\system32\\bash.EXE --noprofile --norc -e -o pipefail {0}: No such file or directory"
+  - "export: The term 'export' is not recognized as the name of a cmdlet"
+root_cause: |
+  GitHub Actions uses a different default shell depending on the runner OS:
+    - Linux (ubuntu-*): bash
+    - macOS (macos-*): bash
+    - Windows (windows-*): PowerShell (pwsh)
+
+  When you write `run:` steps using bash syntax (e.g., `export VAR=value`, `set -e`,
+  `||`, `&&`, heredocs, `$(...)` subshells) without explicitly specifying `shell: bash`,
+  those steps will execute under PowerShell on Windows runners and fail with confusing
+  errors.
+
+  This is especially problematic in:
+    - Matrix workflows that include both Linux and Windows OS variants
+    - Composite actions where the shell is not explicitly set per step
+    - Reusable workflows called from both Linux and Windows jobs
+    - Migration from Linux-only workflows to cross-platform
+
+  A secondary issue: on Windows runners, if `C:\Windows\System32\bash.exe` exists
+  (WSL stub), specifying `shell: bash` may invoke the WSL stub instead of Git Bash
+  (`C:\Program Files\Git\bin\bash.EXE`). This causes "No such file or directory"
+  errors because the WSL stub requires a Linux distribution to be installed.
+  Since runner-images#12646, this is a known issue with no GitHub-side fix.
+
+  Source: actions/runner#1328 (Unable to run bash scripts on Windows runner)
+  Source: runner-images#12646 (Windows WSL bash.exe stub causes shell: bash failures)
+fix: |
+  Always explicitly set `shell: bash` on any `run:` step that uses bash syntax.
+
+  For cross-platform matrix workflows, there are three approaches:
+
+  1. Explicit shell per step — add `shell: bash` to every bash step.
+
+  2. Workflow-level default — set `defaults.run.shell: bash` to apply bash to ALL
+     run steps in the workflow (be consistent — all steps must then use bash syntax).
+
+  3. Job-level default — set `defaults.run.shell: bash` at the job level to scope it.
+
+  If you need PowerShell on Windows AND bash on Linux in the same matrix, use a
+  matrix-aware condition to selectively set the shell, or split into separate jobs.
+fix_code:
+  - language: yaml
+    label: "Fix: explicit shell: bash on individual steps"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+
+            # ✅ Always specify shell: bash for bash scripts
+            - name: Run build script
+              shell: bash         # required on Windows — default is PowerShell
+              run: |
+                export BUILD_ENV=production
+                set -euo pipefail
+                ./scripts/build.sh
+
+  - language: yaml
+    label: "Fix: workflow-level default shell (applies to all run steps)"
+    code: |
+      name: Cross-Platform CI
+
+      defaults:
+        run:
+          shell: bash    # override default — all run steps use bash on all OS
+
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests
+              run: |
+                # This runs in bash on all platforms
+                ./scripts/run-tests.sh
+
+  - language: yaml
+    label: "Anti-pattern: bash syntax without shell: bash on Windows fails"
+    code: |
+      # ❌ WRONG on Windows — default shell is PowerShell, bash syntax breaks
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - name: Set env
+              run: |
+                export DEPLOY_ENV=production    # ← ERROR: 'export' not recognized
+                echo "env: $DEPLOY_ENV"         # ← ERROR: bash variable expansion
+                ls -la                          # ← ERROR: ls -la not valid in pwsh
+
+prevention:
+  - "Always specify `shell: bash` (or `shell: pwsh`) explicitly on every `run:` step in cross-platform workflows."
+  - "Use `defaults.run.shell: bash` at the workflow or job level to reduce repetition."
+  - "Test all matrix OS variants in CI — don't assume Linux behavior translates to Windows."
+  - "For PowerShell-specific steps on Windows, use `shell: pwsh` explicitly rather than relying on the default."
+  - "Avoid relying on the runner's WSL bash stub on Windows — it requires a WSL distribution installed."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/setting-a-default-shell-and-working-directory"
+    label: "GitHub Docs: Setting a default shell and working directory"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell"
+    label: "GitHub Docs: jobs.<job_id>.steps[*].shell"
+  - url: "https://github.com/actions/runner/issues/1328"
+    label: "actions/runner#1328: Unable to run bash scripts on Windows runner"
+  - url: "https://github.com/actions/runner-images/issues/12646"
+    label: "runner-images#12646: Windows WSL bash.exe stub causes shell: bash failures"

package/errors/silent-failures/checkout-fetch-depth-shallow-clone-breaks-history.yml

@@ -0,0 +1,104 @@
+id: silent-failures-013
+title: "Shallow Clone (fetch-depth: 1) Silently Breaks Git History Operations"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - fetch-depth
+  - shallow-clone
+  - git-describe
+  - changelog
+  - versioning
+patterns:
+  - regex: "fatal:.*No names found.*cannot describe anything"
+    flags: "i"
+  - regex: "fatal:.*no tag can describe"
+    flags: "i"
+  - regex: "git describe.*failed with exit code 128"
+    flags: "i"
+  - regex: "fetch-depth.*1"
+    flags: "i"
+error_messages:
+  - "fatal: No names found, cannot describe anything."
+  - "fatal: no tag can describe ''"
+  - "error: process completed with exit code 128"
+  - "git describe --tags --abbrev=0 failed"
+root_cause: |
+  `actions/checkout` defaults to `fetch-depth: 1`, which creates a shallow clone containing
+  only the most recent commit. This means:
+  - No commit history beyond the latest commit is available
+  - No tags are fetched (unless `fetch-tags: true` is set separately)
+  - Git operations that need history context fail silently or produce wrong results
+
+  Affected operations include:
+  - `git describe --tags` — fails with "No names found, cannot describe anything"
+  - `git log --oneline HEAD~10..HEAD` — returns nothing or errors
+  - Semantic versioning tools (semantic-release, standard-version, release-please)
+  - Changelog generators that diff HEAD against previous tags
+  - `git rev-list --count HEAD` — returns "1" instead of full commit count
+  - GitVersion, MinVer, and similar tag-based version calculators
+
+  The failure is silent in many cases: the step appears to succeed, but produces an
+  empty string, "0.0.0", or a fallback version instead of the expected semver.
+
+  Tracked in actions/checkout#217 (RFC: fetch-depth: 1 and not cloning tags are dangerous
+  defaults) with 22 thumbs-up reactions.
+fix: |
+  **Option 1 (recommended for most cases): Fetch full history**
+  Set `fetch-depth: 0` to fetch all commits and tags.
+
+  **Option 2: Fetch only enough history**
+  For large repos, fetch only the depth needed (e.g., last 50 commits). Use
+  `fetch-tags: true` (available in actions/checkout@v4) to fetch all tags without
+  the full commit history.
+
+  **Option 3: Unshallow after checkout**
+  Fetch the necessary history lazily with `git fetch --unshallow` or
+  `git fetch --tags --unshallow` as a subsequent step.
+fix_code:
+  - language: yaml
+    label: "Full history checkout (simplest fix)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # 0 = full history; default 1 = shallow
+
+      - name: Generate changelog
+        run: git log --oneline $(git describe --tags --abbrev=0 @^)..@ --no-merges
+
+  - language: yaml
+    label: "Fetch tags only without full history (faster for large repos)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     # Required for tag-based versioning
+          fetch-tags: true   # Explicitly fetch all tags (actions/checkout v4.1.1+)
+
+  - language: yaml
+    label: "Unshallow lazily if full history is not needed upfront"
+    code: |
+      - uses: actions/checkout@v4
+        # fetch-depth: 1 (default — shallow clone)
+
+      - name: Fetch tags for versioning
+        run: |
+          git fetch --tags --force
+          # Or for full history:
+          # git fetch --unshallow
+
+      - name: Get version from tags
+        run: git describe --tags --abbrev=0
+
+prevention:
+  - "Add `fetch-depth: 0` to any checkout step that precedes git history, tag, or versioning operations."
+  - "Set `fetch-tags: true` in actions/checkout@v4 when using tag-based versioning tools."
+  - "When using semantic-release, release-please, or GitVersion, always use `fetch-depth: 0`."
+  - "Test locally with `git clone --depth 1` to reproduce the shallow clone environment before debugging in CI."
+  - "Audit all checkout steps in release workflows — shallow clones are fine for build/test but break release automation."
+docs:
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout: fetch-depth and fetch-tags inputs"
+  - url: "https://github.com/actions/checkout/issues/217"
+    label: "actions/checkout#217: RFC — fetch-depth: 1 and not cloning tags are dangerous defaults"
+  - url: "https://stackoverflow.com/questions/66349002/get-latest-tag-git-describe-tags-when-repo-is-cloned-with-depth-1"
+    label: "Stack Overflow: git describe fails when cloned with depth=1"

package/errors/silent-failures/pull-request-ref-is-merge-ref.yml

@@ -0,0 +1,134 @@
+id: silent-failures-014
+title: "pull_request github.ref Is refs/pull/N/merge — Branch-Name Conditions Silently Evaluate to False"
+category: silent-failures
+severity: silent-failure
+tags:
+  - pull_request
+  - github-ref
+  - merge-ref
+  - branch-name
+  - if-condition
+  - head-ref
+  - base-ref
+patterns:
+  - regex: "github\\.ref\\s*==\\s*['\"]refs/heads/"
+    flags: "i"
+  - regex: "GITHUB_REF.*refs/pull/\\d+/merge"
+    flags: "i"
+  - regex: "github\\.ref.*startsWith.*refs/heads"
+    flags: "i"
+error_messages:
+  - "refs/pull/123/merge"
+  - "Conditional check 'github.ref == refs/heads/main' evaluated to false on pull_request event"
+  - "GITHUB_REF=refs/pull/47/merge"
+root_cause: |
+  When a workflow is triggered by the `pull_request` (or `pull_request_target`) event,
+  `github.ref` is set to `refs/pull/<number>/merge` — NOT the source branch name.
+
+  This `refs/pull/<N>/merge` is a synthetic Git reference created by GitHub representing
+  the prospective merge commit (the merge of the PR's head branch into the base branch).
+  It does not correspond to any named branch.
+
+  Developers commonly write conditions expecting `github.ref` to contain the branch name:
+    - `if: github.ref == 'refs/heads/feature-branch'`  → always false on PR events
+    - `if: startsWith(github.ref, 'refs/heads/')`       → always false on PR events
+    - `if: github.ref != 'refs/heads/main'`             → always true on PR events
+
+  These conditions silently pass or silently skip — no error is reported. The job
+  simply runs (or doesn't run) with no indication that the ref check was wrong.
+
+  The correct context variables for PR events are:
+    - `github.head_ref` — the source branch name (e.g., "feature/my-branch")
+    - `github.base_ref` — the target branch name (e.g., "main")
+    - `github.event.pull_request.head.ref` — same as head_ref
+    - `github.event.pull_request.base.ref` — same as base_ref
+
+  Note: `github.head_ref` and `github.base_ref` are ONLY set for pull_request events.
+  For push events, use `github.ref_name` instead.
+
+  Source: Stack Overflow #68708792 (what is github.ref when merging PR to master)
+  Source: Stack Overflow #78162051 (obtain branch name in github action on pull_request)
+  Docs: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context
+fix: |
+  Use the correct context variable depending on what information you need:
+
+  For the PR source branch:
+    Use `github.head_ref` (not `github.ref`)
+
+  For the PR target branch:
+    Use `github.base_ref` (not `github.ref`)
+
+  For branch-scoped conditions that need to work across BOTH push and pull_request:
+    Use `github.ref_name` (gives branch/tag name without refs/heads/ prefix)
+    Or use `github.event_name` to gate the condition by event type
+
+  To check if a push or PR targets the main branch:
+    - Push: `github.ref == 'refs/heads/main'`
+    - PR:   `github.base_ref == 'main'`
+    - Both: use separate conditions gated by `github.event_name`
+fix_code:
+  - language: yaml
+    label: "Fix: use github.head_ref for PR source branch, base_ref for target"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            # ❌ WRONG: github.ref on pull_request is refs/pull/N/merge — never matches heads/*
+            - name: Wrong branch check
+              if: github.ref == 'refs/heads/feature-branch'  # always false on PR!
+              run: echo "this never runs on PR events"
+
+            # ✅ CORRECT: use head_ref for the source branch name
+            - name: Correct branch check
+              if: github.head_ref == 'feature-branch'
+              run: echo "this runs when PR source branch is feature-branch"
+
+            # ✅ CORRECT: use base_ref for the target branch name
+            - name: Check if targeting main
+              if: github.base_ref == 'main'
+              run: echo "this PR is targeting main"
+
+  - language: yaml
+    label: "Cross-event condition: works for both push and pull_request"
+    code: |
+      jobs:
+        conditional:
+          runs-on: ubuntu-latest
+          steps:
+            # Works for both push (github.ref_name) and PR (github.base_ref)
+            - name: Is this targeting/on main?
+              if: |
+                (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
+                (github.event_name == 'pull_request' && github.base_ref == 'main')
+              run: echo "targeting or on main branch"
+
+            # Simpler: github.ref_name works for push; for PR it returns the merge ref number
+            # Best to keep push and pull_request logic separate with event_name guards
+
+  - language: yaml
+    label: "Debug step: print all relevant refs for troubleshooting"
+    code: |
+      - name: Debug refs
+        run: |
+          echo "event_name:  ${{ github.event_name }}"
+          echo "ref:         ${{ github.ref }}"
+          echo "ref_name:    ${{ github.ref_name }}"
+          echo "head_ref:    ${{ github.head_ref }}"
+          echo "base_ref:    ${{ github.base_ref }}"
+          # On push/branch: ref=refs/heads/main, head_ref='', base_ref=''
+          # On pull_request: ref=refs/pull/47/merge, head_ref=feature-x, base_ref=main
+
+prevention:
+  - "Never use `github.ref` to get the branch name in `pull_request` triggered workflows — it is not a branch ref."
+  - "Use `github.head_ref` for the PR source branch and `github.base_ref` for the target branch."
+  - "For conditions that span both push and pull_request events, gate on `github.event_name` first."
+  - "Add a debug step printing `github.ref`, `github.head_ref`, and `github.base_ref` when debugging trigger conditions."
+  - "Use `github.ref_name` (branch/tag name without prefix) for push events instead of stripping `refs/heads/` manually."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub Docs: github context (ref, head_ref, base_ref, ref_name)"
+  - url: "https://stackoverflow.com/questions/68708792/what-is-github-ref-when-merging-pr-to-master"
+    label: "Stack Overflow: What is github.ref when merging PR to master?"
+  - url: "https://stackoverflow.com/questions/78162051/obtain-branch-name-in-github-action-on-pull-request"
+    label: "Stack Overflow: Obtain branch name in github action on pull request"

package/errors/triggers/push-paths-filter-bypassed-by-tag.yml

@@ -0,0 +1,123 @@
+id: triggers-012
+title: "Tag Pushes Bypass paths: Filter — Workflow Fires on Every Tag Regardless of Changed Files"
+category: triggers
+severity: silent-failure
+tags:
+  - push
+  - tags
+  - paths-filter
+  - tag-push
+  - trigger
+  - branches
+patterns:
+  - regex: "on:\\s*\\n\\s*push:\\s*\\n\\s*(\\w[^\\n]*\\n\\s*)*paths:"
+    flags: "im"
+  - regex: "Triggered by refs/tags/"
+    flags: "i"
+  - regex: "push.*paths.*tags.*ignored"
+    flags: "i"
+error_messages:
+  - "Run triggered by push to refs/tags/v1.0.0"
+  - "Evaluation skipped: tag push does not evaluate path filters"
+root_cause: |
+  GitHub Actions evaluates `paths:` and `paths-ignore:` filters ONLY for branch pushes.
+  When a tag is pushed, path filters are completely bypassed — the workflow runs regardless
+  of which files were changed.
+
+  This means a workflow like:
+
+    on:
+      push:
+        paths:
+          - "src/**"
+
+  will fire on every tag push (e.g., `git push origin v1.2.3`) even if no files under
+  `src/` were modified in the tagged commit.
+
+  Additionally, if a workflow has `on: push:` with NO branches/tags filter, a tag push
+  produces a `push` webhook event that triggers the workflow. Developers expect tag pushes
+  to be governed by path filters, but the docs explicitly state path filters are not
+  evaluated for tag events.
+
+  Source: actions/runner#3933 (path filters not respected for tag pushes)
+  Source: Stack Overflow #76037078 (paths also triggered when pushing a new tag)
+  Docs: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters-to-target-specific-paths-for-pull-request-or-push-events
+fix: |
+  If you want path-filtered push workflows to run ONLY on branch pushes (not tag pushes),
+  explicitly add a `tags-ignore: ["**"]` filter or restrict to branches explicitly.
+
+  Option A — Add `tags-ignore` to suppress all tag events:
+    on:
+      push:
+        paths:
+          - "src/**"
+        tags-ignore:
+          - "**"
+
+  Option B — Add an explicit `branches` filter (only branch pushes match):
+    on:
+      push:
+        branches:
+          - "**"         # all branches
+        paths:
+          - "src/**"
+
+  Note: Option B is equivalent — defining `branches` or `tags` implicitly excludes the
+  other git ref type from triggering the workflow.
+fix_code:
+  - language: yaml
+    label: "Add tags-ignore to prevent tag pushes from bypassing path filters"
+    code: |
+      on:
+        push:
+          # Path filter only works for branch pushes — add tags-ignore to prevent
+          # tag pushes from triggering this workflow unconditionally.
+          tags-ignore:
+            - "**"
+          paths:
+            - "src/**"
+            - "lib/**"
+
+  - language: yaml
+    label: "Restrict to all branches (implicitly excludes tags)"
+    code: |
+      on:
+        push:
+          branches:
+            - "**"         # matches all branch pushes, ignores tag pushes
+          paths:
+            - "src/**"
+
+  - language: yaml
+    label: "Separate workflows for branch CI vs tag release"
+    code: |
+      # ci.yml — triggered by branch pushes with path filtering
+      on:
+        push:
+          branches:
+            - main
+            - "feature/**"
+          paths:
+            - "src/**"
+
+      ---
+      # release.yml — triggered by version tags
+      on:
+        push:
+          tags:
+            - "v*.*.*"
+
+prevention:
+  - "Never rely on `paths:` filters to suppress tag-push triggers — they are not evaluated for tags."
+  - "Always add an explicit `branches:` or `tags-ignore: [\"**\"]` when your workflow is path-filtered and meant only for code changes."
+  - "Keep branch-CI workflows and release/tag workflows in separate files to avoid trigger ambiguity."
+  - "Test your trigger logic with `act` locally — push a tag and verify the workflow does not fire unexpectedly."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters-to-target-specific-paths-for-pull-request-or-push-events"
+    label: "GitHub Docs: Using filters to target specific paths"
+  - url: "https://github.com/actions/runner/issues/3933"
+    label: "actions/runner#3933: Path filters not respected for tag pushes"
+  - url: "https://stackoverflow.com/questions/76037078/why-is-my-github-action-on-paths-also-triggered-when-pushing-a-new-tag"
+    label: "Stack Overflow: Why is paths: also triggered when pushing a new tag?"
+  - url: "https://stackoverflow.com/questions/70743715/how-do-i-configure-a-github-actions-workflow-so-it-does-not-run-on-a-tag-push"
+    label: "Stack Overflow: How to prevent workflow from running on tag push"

package/errors/triggers/workflow-dispatch-filters-silently-ignored.yml

@@ -0,0 +1,131 @@
+id: triggers-011
+title: "workflow_dispatch branches/paths Filters Silently Ignored or Cause Validation Error"
+category: triggers
+severity: warning
+tags:
+  - workflow_dispatch
+  - branches
+  - paths
+  - filters
+  - trigger
+  - manual-dispatch
+patterns:
+  - regex: "Unexpected value 'branches'"
+    flags: "i"
+  - regex: "workflow_dispatch.*branches.*paths"
+    flags: "i"
+  - regex: "The workflow is not valid.*Unexpected value"
+    flags: "i"
+  - regex: "on\\.workflow_dispatch.*branches"
+    flags: "i"
+error_messages:
+  - "The workflow is not valid. .github/workflows/deploy.yml (Line: X, Col: Y): Unexpected value 'branches'"
+  - "Unexpected value 'branches'"
+  - "Unexpected value 'tags'"
+  - "Unexpected value 'paths'"
+root_cause: |
+  `workflow_dispatch` is a manual trigger — it runs when a user (or the API) explicitly
+  triggers the workflow. Because it is not event-driven by a push or pull request, the
+  `branches`, `paths`, `tags`, and `paths-ignore` filters that apply to push/pull_request
+  events are **not valid** for `workflow_dispatch`.
+
+  Two failure modes exist:
+
+  **Mode 1: Validation error (branches, tags)**
+  Adding `branches` or `tags` under `on.workflow_dispatch` now produces a schema
+  validation error: "Unexpected value 'branches'" or "Unexpected value 'tags'".
+  GitHub used to silently ignore these keys (pre-2022), leading to copy-paste templates
+  with these keys still floating around. The workflow may fail to queue at all.
+
+  **Mode 2: Silent ignore (paths)**
+  The `paths` filter under `on.workflow_dispatch` was silently ignored historically.
+  The workflow runs regardless of which files changed (or didn't change), because
+  workflow_dispatch has no file-change context to filter on.
+
+  Developers commonly copy a push-triggered workflow and add workflow_dispatch without
+  removing the push-specific filters, producing this mistake:
+
+  ```yaml
+  on:
+    push:
+      branches: [main]
+      paths: ['src/**']
+    workflow_dispatch:
+      branches: [main]   # ← INVALID for workflow_dispatch
+      paths: ['src/**']  # ← silently ignored for workflow_dispatch
+  ```
+
+  Tracked in github/docs#34884 ("documentation on workflow_dispatch is not
+  correct/complete") and blog post by Jon Gallant (2022): "workflow_dispatch never
+  supported branches, but GH silently ignored it."
+fix: |
+  Remove `branches`, `paths`, `tags`, and `paths-ignore` from the `workflow_dispatch`
+  block entirely. These filters only apply to `push`, `pull_request`, and
+  `pull_request_target` triggers.
+
+  If you want manual dispatch to only be available on specific branches, use the
+  GitHub Actions UI branch selector at runtime — it allows choosing which branch to
+  run the workflow on during manual dispatch without needing a filter in the YAML.
+
+  If you need path-based conditional logic in a manually-triggered workflow, use
+  `dorny/paths-filter` or a custom `git diff` step to check which files changed after
+  the workflow starts.
+fix_code:
+  - language: yaml
+    label: "Remove invalid filters from workflow_dispatch block"
+    code: |
+      on:
+        push:
+          branches: [main]
+          paths: ['src/**']   # ← valid here for push
+        workflow_dispatch:
+          # ← Do NOT add branches/paths/tags here — they are not supported
+          # Use inputs if you need runtime parameterization:
+          inputs:
+            environment:
+              description: "Target environment"
+              required: true
+              default: "staging"
+              type: choice
+              options: [staging, production]
+
+  - language: yaml
+    label: "Path-based conditional logic inside a manually-dispatched workflow"
+    code: |
+      on:
+        workflow_dispatch:
+
+      jobs:
+        check-and-deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 2
+
+            - name: Check changed paths
+              id: filter
+              uses: dorny/paths-filter@v3
+              with:
+                filters: |
+                  src:
+                    - 'src/**'
+
+            - name: Deploy (only if src changed)
+              if: steps.filter.outputs.src == 'true'
+              run: echo "Deploying..."
+
+prevention:
+  - "Never copy `branches`, `paths`, or `tags` filters from a `push` block into a `workflow_dispatch` block."
+  - "Treat `workflow_dispatch` as a parameter-based trigger, not a filter-based one — use `inputs` instead."
+  - "If the GitHub Actions linter flags 'Unexpected value branches', remove it from the workflow_dispatch block."
+  - "Use the branch selector in the GitHub Actions UI for branch scoping at runtime."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Docs: workflow_dispatch event trigger"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore"
+    label: "GitHub Docs: paths filter (push/pull_request only)"
+  - url: "https://github.com/github/docs/issues/34884"
+    label: "github/docs#34884: documentation on workflow_dispatch is not correct/complete"
+  - url: "https://blog.jongallant.com/2022/04/github-actions-failing-with-unexpected-value-branches"
+    label: "Jon Gallant: workflow_dispatch never supported branches (2022)"

package/errors/yaml-syntax/matrix-include-extra-standalone-jobs.yml

@@ -0,0 +1,136 @@
+id: yaml-syntax-017
+title: "Matrix include Entry Without Matching Combination Creates Unexpected Standalone Jobs"
+category: yaml-syntax
+severity: warning
+tags:
+  - matrix
+  - include
+  - strategy
+  - extra-jobs
+  - standalone
+  - job-count
+patterns:
+  - regex: "strategy.*matrix.*include"
+    flags: "i"
+  - regex: "matrix.*include.*extra.*job"
+    flags: "i"
+  - regex: "include.*os.*version"
+    flags: "i"
+error_messages:
+  - "strategy.matrix.include"
+  - "unexpected job combination in matrix"
+root_cause: |
+  GitHub Actions matrix `include` entries serve two purposes:
+  1. **Add variables to existing combinations** — when the entry shares at least one
+     key-value pair with an existing matrix combination, it adds/overrides variables
+     for that specific combination only.
+  2. **Create new standalone jobs** — when the entry does NOT match any existing matrix
+     combination, GitHub Actions treats it as an entirely NEW matrix job on its own.
+
+  This second behavior surprises developers who expect `include` to only add metadata
+  to existing jobs. Example that creates an unexpected extra job:
+
+  ```yaml
+  strategy:
+    matrix:
+      os: [ubuntu-latest, windows-latest]
+      node: [18, 20]
+      include:
+        - os: macos-latest      # ← No matching {os: macos-latest} in matrix
+          node: 20
+          experimental: true   # ← This creates a BRAND NEW 5th job, not expected
+  ```
+
+  The matrix produces: 4 jobs from combinations (ubuntu×18, ubuntu×20,
+  windows×18, windows×20) PLUS an extra 5th job for (macos-latest × 20 × experimental).
+
+  This can also cause subtle bugs when a typo in an `include` value fails to match
+  the existing combination, silently creating an extra duplicate-like job:
+
+  ```yaml
+  include:
+    - os: ubuntu-latest   # os key matches!
+      node: 18
+      runs-long: true     # Variable added to ubuntu-latest×18 job ✓
+    - os: ubuntu          # TYPO: doesn't match "ubuntu-latest" → new standalone job ✗
+      node: 18
+      experimental: true
+  ```
+
+  Tracked in github/docs#23322 ("Documentation for jobs matrix strategy seems incorrect").
+fix: |
+  **To add variables to existing combinations:** Ensure at least one key in the
+  `include` entry exactly matches an existing combination value. The match is
+  case-sensitive.
+
+  **To intentionally add a new job:** This is valid behavior — just document it clearly
+  in the workflow and be aware of the extra job in your branch protection rules.
+
+  **To prevent accidental extra jobs:** Review the job count after adding include entries.
+  The total should be: (product of all matrix dimensions) + (number of include entries
+  that don't match any combination).
+fix_code:
+  - language: yaml
+    label: "include entry that correctly adds a variable to an existing combination"
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, windows-latest]
+          node: [18, 20]
+          include:
+            # This MATCHES ubuntu-latest×18 — adds 'experimental: true' to that job only
+            - os: ubuntu-latest  # ← must exactly match the matrix value
+              node: 18           # ← must exactly match the matrix value
+              experimental: true
+
+            # This MATCHES all ubuntu-latest jobs (node 18 AND 20)
+            # because os key matches and node is not specified
+            - os: ubuntu-latest
+              runs-slow: true    # added to ubuntu-latest×18 AND ubuntu-latest×20
+
+  - language: yaml
+    label: "Intentional standalone job via include (extra OS not in base matrix)"
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, windows-latest]
+          node: [18, 20]
+          include:
+            # Intentional extra job — macos is not in the base matrix
+            # Documents clearly that this creates job #5 (macos×20)
+            - os: macos-latest
+              node: 20
+              experimental: true
+      # Total jobs: 4 (base combinations) + 1 (macos standalone) = 5
+
+  - language: yaml
+    label: "Verify total job count matches expectations with exclude"
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, windows-latest, macos-latest]
+          node: [18, 20]
+          exclude:
+            # Exclude expensive macos×18 — not needed
+            - os: macos-latest
+              node: 18
+          include:
+            # Add experimental flag to ubuntu-latest×20 only
+            - os: ubuntu-latest
+              node: 20
+              experimental: true
+      # Total jobs: (3×2) - 1 excluded = 5 jobs; 0 new from include (it matches existing)
+
+prevention:
+  - "Always verify the total expected job count after adding `include` entries."
+  - "Ensure `include` key-value pairs exactly match (case-sensitive) the base matrix values."
+  - "Use a comment in the workflow to document the expected total number of jobs."
+  - "If a typo causes an unexpected extra job, it will show up as a job with no matching `if:` context — watch for jobs that run but shouldn't."
+  - "Use `exclude` to remove specific combinations instead of relying solely on `include` overrides."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow#expanding-or-adding-matrix-configurations"
+    label: "GitHub Docs: Expanding or adding matrix configurations with include"
+  - url: "https://github.com/github/docs/issues/23322"
+    label: "github/docs#23322: Documentation for jobs matrix strategy seems incorrect"
+  - url: "https://stackoverflow.com/questions/78821409/github-actions-matrix-job-running-despite-false-conditions"
+    label: "Stack Overflow: GitHub Actions matrix job running despite false conditions"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",