@htekdev/actions-debugger 1.0.10 → 1.0.11

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/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/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/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.11",
   "description": "65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",