@htekdev/actions-debugger 1.0.14 → 1.0.16

package/errors/triggers/push-event-fires-on-branch-delete.yml

@@ -0,0 +1,129 @@
+id: triggers-015
+title: "on: push Fires When a Branch Is Deleted — Unguarded Workflows Fail"
+category: triggers
+severity: error
+tags:
+  - push
+  - branch-delete
+  - github.event.deleted
+  - ref-not-found
+  - workflow-trigger
+  - branch-cleanup
+patterns:
+  - regex: "on:\\s*push"
+    flags: "im"
+  - regex: "github\\.event\\.deleted"
+    flags: "i"
+  - regex: "fatal.*not.*a.*git repository|fatal.*couldn't find remote ref"
+    flags: "i"
+error_messages:
+  - "fatal: couldn't find remote ref refs/heads/my-feature-branch"
+  - "Error: The process '/usr/bin/git' failed with exit code 128"
+  - "fatal: not a git repository (or any of the parent directories): .git"
+  - "remote: Repository not found"
+root_cause: |
+  GitHub's `push` webhook fires on ALL ref write operations, including branch and tag
+  deletions. When a branch is deleted, a push event is emitted with:
+    - `github.event.deleted == true`
+    - `github.event.created == false`
+    - `github.ref` set to the deleted branch ref (e.g., `refs/heads/feature-xyz`)
+    - `github.event.after` set to `0000000000000000000000000000000000000000` (40 zeros)
+    - `github.sha` reverts to the default branch SHA
+
+  Workflows triggered by `on: push` that do not guard against deletion events can:
+  - Fail when `actions/checkout` tries to check out a branch that no longer exists
+  - Trigger deployment pipelines, test suites, or notification workflows unexpectedly
+  - Produce misleading failures that look like unrelated CI breakage
+
+  This is especially problematic in workflows that:
+  - Checkout a specific branch ref from `github.ref`
+  - Run clean-up scripts expecting the branch to exist
+  - Use `git describe` or `git log` on the tip of the deleted branch
+
+  GitHub documentation notes: "When you delete a branch, the SHA in the workflow run
+  (and its associated refs) reverts to the default branch of the repository."
+  Source: GitHub Docs — Events that trigger workflows (push event payload)
+  Source: GitHub Docs — Webhook events and payloads (`deleted` field on push payload)
+fix: |
+  Add an `if:` guard to any job or workflow step that should not run on branch deletions.
+  The `github.event.deleted` context field is `true` when the push event is a deletion.
+
+  For most push-triggered workflows, the intent is to react to new commits — guard with:
+    `if: github.event.deleted != true`
+
+  For tag deletion events, also check `github.event.ref_type` if you use the `delete`
+  event, or use `if: github.event.deleted != true && !startsWith(github.ref, 'refs/tags/')`.
+
+  Alternatively, use the `on: delete` event for branch/tag cleanup workflows instead of
+  listening for deletions via the push event.
+fix_code:
+  - language: yaml
+    label: "Guard push jobs from running on branch deletion"
+    code: |
+      on:
+        push:
+          branches:
+            - 'feature/**'
+            - 'fix/**'
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # ✅ Skip the job entirely when the push is a branch deletion
+          if: github.event.deleted != true
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+
+  - language: yaml
+    label: "Per-step guard if you need some steps to run on deletion"
+    code: |
+      jobs:
+        process:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Checkout (skip on delete)
+              if: github.event.deleted != true
+              uses: actions/checkout@v4
+
+            - name: Run tests (skip on delete)
+              if: github.event.deleted != true
+              run: npm test
+
+            - name: Log branch deleted
+              if: github.event.deleted == true
+              run: echo "Branch ${{ github.ref_name }} was deleted"
+
+  - language: yaml
+    label: "Use on: delete event for cleanup workflows instead"
+    code: |
+      # Prefer the dedicated 'delete' event for branch/tag cleanup
+      on:
+        delete:
+          # Optionally filter to branches only (not tags)
+
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          # github.event.ref is the deleted branch/tag name
+          # github.event.ref_type is 'branch' or 'tag'
+          if: github.event.ref_type == 'branch'
+          steps:
+            - name: Clean up preview environment
+              run: |
+                echo "Cleaning up for deleted branch: ${{ github.event.ref }}"
+                ./scripts/teardown-preview.sh "${{ github.event.ref }}"
+
+prevention:
+  - "Add `if: github.event.deleted != true` to all jobs in `on: push` workflows."
+  - "Use the `on: delete` event for branch/tag teardown workflows instead of catching deletions via push."
+  - "Check `github.event.after == '0000000000000000000000000000000000000000'` as an alternative deletion guard."
+  - "Avoid checking out `${{ github.ref }}` directly; use `actions/checkout` defaults which handle this gracefully."
+  - "Add branch filters under `on: push: branches:` to limit which branches trigger the workflow."
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "GitHub Docs: push webhook event payload (deleted field)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Docs: push event trigger"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#delete"
+    label: "GitHub Docs: delete event trigger"

package/errors/triggers/push-first-commit-before-sha-zeros.yml

@@ -0,0 +1,160 @@
+id: triggers-014
+title: "github.event.before Is All Zeros on First Push to a New Branch — git diff Fails"
+category: triggers
+severity: error
+tags:
+  - push
+  - first-push
+  - git-diff
+  - before-sha
+  - new-branch
+  - branch-creation
+patterns:
+  - regex: "fatal.*bad revision.*0000000000000000000000000000000000000000"
+    flags: "i"
+  - regex: "fatal.*ambiguous argument '0{40}'"
+    flags: "i"
+  - regex: "unknown revision or path not in the working tree.*0{10}"
+    flags: "i"
+  - regex: "0{40}\\.\\.\\.\\$\\{\\{.*github\\.event\\.before"
+    flags: "i"
+error_messages:
+  - "fatal: bad revision '0000000000000000000000000000000000000000...HEAD'"
+  - "fatal: ambiguous argument '0000000000000000000000000000000000000000': unknown revision or path not in the working tree"
+  - "error: object file .git/objects/00/00000000000000000000000000000000000000 is empty"
+root_cause: |
+  When a **new branch is pushed for the first time**, `github.event.before` is set to
+  `0000000000000000000000000000000000000000` (40 zeros), representing the null/empty SHA.
+  This indicates there was no previous commit on this branch — it is a branch creation event.
+
+  Workflows that use `github.event.before` to compute a diff range (e.g., to find changed
+  files) fail when run on a first push because `git diff` or `git log` cannot resolve the
+  null SHA:
+
+  ```yaml
+  run: git diff ${{ github.event.before }}...HEAD
+  # On first push: git diff 0000000000000000000000000000000000000000...HEAD → FATAL ERROR
+  ```
+
+  **When this occurs:**
+  - First push to a new branch (branch creation)
+  - `push` events that create a new branch (`github.event.created == true`)
+  - Forced pushes that reference a non-existent before-SHA (rare)
+
+  **Why it's painful:**
+  - Workflows work fine for subsequent pushes (where `before` is a real commit)
+  - The error only appears on the first push, often during branch creation in a PR workflow
+  - The error message references the git object store internals, not the workflow context
+  - Developers check out the diff command syntax without realizing the SHA is invalid
+fix: |
+  **Option 1 (recommended): Guard against the null SHA before running git diff**
+
+  Check if `github.event.before` is the null SHA and fall back to diffing against the
+  merge base or the initial commit.
+
+  **Option 2: Use the `dorny/paths-filter` action**
+
+  The `dorny/paths-filter` action handles first-push, force-push, and all edge cases
+  in branch diff computation automatically.
+
+  **Option 3: Use `github.event.created` to skip diff-based logic on branch creation**
+
+  Add an `if: github.event.created != true` guard to diff-dependent steps so they only
+  run on non-creation push events.
+fix_code:
+  - language: yaml
+    label: "Broken — git diff with github.event.before fails on first push"
+    code: |
+      # ❌ BROKEN: Fails when branch is pushed for the first time
+      on: push
+
+      jobs:
+        lint-changed:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 0
+            - name: Lint only changed files
+              run: |
+                CHANGED=$(git diff --name-only ${{ github.event.before }}...HEAD)
+                # FATAL on first push: 0000000000000000000000000000000000000000 is not a commit
+  - language: yaml
+    label: "Fixed — guard against null SHA before git diff"
+    code: |
+      # ✅ FIXED: Check for null SHA and fall back to first commit
+      on: push
+
+      jobs:
+        lint-changed:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 0
+            - name: Lint only changed files
+              run: |
+                BEFORE="${{ github.event.before }}"
+                NULL_SHA="0000000000000000000000000000000000000000"
+
+                if [ "$BEFORE" = "$NULL_SHA" ]; then
+                  # First push to new branch — diff against the initial commit or all files
+                  echo "First push to branch, diffing all files"
+                  CHANGED=$(git diff --name-only $(git rev-list --max-parents=0 HEAD)...HEAD)
+                else
+                  CHANGED=$(git diff --name-only "$BEFORE"...HEAD)
+                fi
+                echo "$CHANGED"
+  - language: yaml
+    label: "Fixed — skip diff steps on branch creation using github.event.created"
+    code: |
+      # ✅ FIXED: Skip diff-based steps entirely on first push (branch creation)
+      on: push
+
+      jobs:
+        lint-changed:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 0
+            - name: Lint only changed files
+              # Skip on branch creation (before SHA is null)
+              if: github.event.created != true
+              run: |
+                git diff --name-only ${{ github.event.before }}...HEAD | xargs eslint
+  - language: yaml
+    label: "Fixed — use dorny/paths-filter which handles null SHA automatically"
+    code: |
+      # ✅ RECOMMENDED: dorny/paths-filter handles first-push and force-push edge cases
+      on: push
+
+      jobs:
+        lint-changed:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: dorny/paths-filter@v3
+              id: changes
+              with:
+                filters: |
+                  src:
+                    - 'src/**'
+                  tests:
+                    - 'tests/**'
+            - name: Lint src changes
+              if: steps.changes.outputs.src == 'true'
+              run: npm run lint
+prevention:
+  - "Never use `git diff ${{ github.event.before }}` without guarding against the null SHA (`0000000000000000000000000000000000000000`) — this is guaranteed to fail on first push."
+  - "Prefer `dorny/paths-filter` for changed-file detection — it handles all SHA edge cases (first push, force push, merge commits) internally."
+  - "If you must use raw git diff, always add: `if [ \"$BEFORE\" = \"$NULL_SHA\" ]; then echo 'first push'; exit 0; fi`."
+  - "Test your diff workflows by creating a fresh test branch — don't only test on subsequent pushes where `before` is always valid."
+  - "Use `github.event.created == true` in `if:` conditions to identify branch creation events and handle them separately."
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "GitHub Docs: push webhook event payload — before field"
+  - url: "https://github.com/dorny/paths-filter"
+    label: "dorny/paths-filter — changed file detection with edge case handling"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Docs: Events that trigger workflows — push"

package/errors/yaml-syntax/continue-on-error-env-context-rejected.yml

@@ -0,0 +1,130 @@
+id: yaml-syntax-022
+title: "env Context Rejected in continue-on-error and Other Job-Level Boolean Attributes"
+category: yaml-syntax
+severity: error
+tags:
+  - continue-on-error
+  - env-context
+  - expression
+  - job-level
+  - unrecognized-named-value
+  - context-availability
+patterns:
+  - regex: "Unrecognized named-value: 'env'"
+    flags: "i"
+  - regex: "Unexpected value.*env\\."
+    flags: "i"
+  - regex: "continue-on-error.*env\\.|env\\..*continue-on-error"
+    flags: "i"
+  - regex: "The workflow is not valid.*Unrecognized named-value: 'env'"
+    flags: "i"
+error_messages:
+  - "The workflow is not valid. .github/workflows/ci.yml (Line X, Col Y): Unrecognized named-value: 'env'. Located at position 1 within expression: env.MY_FLAG"
+  - "Unexpected value '${{ contains(env.MY_LIST, matrix.value) }}'"
+root_cause: |
+  The `env` context is NOT available in all workflow attribute positions. Specifically,
+  job-level and step-level attributes that accept boolean values or simple flags — such as
+  `continue-on-error`, `timeout-minutes` (value expressions), and similar fields — do not
+  support the `env` context in their expression evaluations.
+
+  This is a known GitHub Actions platform limitation documented in actions/runner#1492. The
+  error occurs because these attributes are evaluated at workflow parse/validation time (before
+  the job runs), when environment variables have not yet been set in the runner context.
+
+  Contexts available in `continue-on-error`:
+  - ✅ `github`, `needs`, `strategy`, `matrix`
+  - ❌ `env`, `secrets`, `steps`, `jobs`
+
+  A common pattern that fails:
+  ```yaml
+  steps:
+    - run: ./build.sh
+      continue-on-error: ${{ contains(env.SUPPORTED_VERSIONS, matrix.version) }}
+  ```
+
+  Even if `env.SUPPORTED_VERSIONS` was set in the `env:` block at the top of the workflow,
+  the expression fails because `env` is not a supported context in that attribute.
+fix: |
+  Move the boolean logic into a step output computed earlier in the job, then reference the
+  step output in `continue-on-error`. Alternatively, restructure the workflow to avoid needing
+  `env`-based expressions in boolean job/step attributes.
+
+  **Option 1**: Compute the flag in an earlier step and use `steps` context:
+  ```yaml
+  - id: check
+    run: echo "should_skip=$([[ "$MY_FLAG" == "true" ]] && echo true || echo false)" >> $GITHUB_OUTPUT
+  - run: ./potentially-failing-task.sh
+    continue-on-error: ${{ steps.check.outputs.should_skip == 'true' }}
+  ```
+
+  **Option 2**: Use `matrix` context directly (supported in continue-on-error):
+  ```yaml
+  strategy:
+    matrix:
+      experimental: [true, false]
+  steps:
+    - run: ./build.sh
+      continue-on-error: ${{ matrix.experimental }}
+  ```
+
+  **Option 3**: Wrap the step in a conditional run script that handles the error inline.
+fix_code:
+  - language: yaml
+    label: "Use step output to control continue-on-error dynamically"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          env:
+            EXPERIMENTAL_VERSIONS: "3.12 3.13"
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ This FAILS: env context not available in continue-on-error
+            # - run: pytest
+            #   continue-on-error: ${{ contains(env.EXPERIMENTAL_VERSIONS, matrix.python) }}
+
+            # ✅ Compute the flag first, then reference via steps context
+            - id: flags
+              run: |
+                if echo "$EXPERIMENTAL_VERSIONS" | grep -qw "${{ matrix.python }}"; then
+                  echo "experimental=true" >> $GITHUB_OUTPUT
+                else
+                  echo "experimental=false" >> $GITHUB_OUTPUT
+                fi
+            - run: pytest
+              continue-on-error: ${{ steps.flags.outputs.experimental == 'true' }}
+  - language: yaml
+    label: "Use matrix boolean directly (no env needed)"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              include:
+                - python: "3.11"
+                  experimental: false
+                - python: "3.12"
+                  experimental: true
+                - python: "3.13"
+                  experimental: true
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python }}
+            - run: pytest
+              continue-on-error: ${{ matrix.experimental }}   # ✅ matrix context IS supported
+prevention:
+  - "Check the GitHub Actions context availability table before using any context in job-level attributes — not all contexts are available everywhere."
+  - "When you need dynamic boolean flags in `continue-on-error`, compute them in an earlier step and read via `steps.<id>.outputs`."
+  - "The `matrix` context is fully supported in `continue-on-error` — prefer encoding experimental flags in the matrix definition."
+  - "Run `actionlint` on your workflow to catch context-availability errors before pushing."
+docs:
+  - url: "https://github.com/actions/runner/issues/1492"
+    label: "actions/runner#1492 — env context not available in continue-on-error (original report)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#context-availability"
+    label: "GitHub Docs — context availability table (where each context can be used)"
+  - url: "https://github.com/rhysd/actionlint"
+    label: "actionlint — static analyzer that catches context-availability errors"

package/errors/yaml-syntax/fromjson-empty-string-crash.yml

@@ -0,0 +1,99 @@
+id: yaml-syntax-021
+title: "fromJSON() on empty or undefined step output throws Unexpected end of JSON input"
+category: yaml-syntax
+severity: error
+tags:
+  - fromjson
+  - outputs
+  - expression
+  - json
+  - step-outputs
+  - dynamic-matrix
+patterns:
+  - regex: "Unexpected end of JSON input"
+    flags: "i"
+  - regex: "Invalid JSON for parameter"
+    flags: "i"
+  - regex: "is not valid JSON"
+    flags: "i"
+  - regex: "fromJSON.*failed"
+    flags: "i"
+error_messages:
+  - "Unexpected end of JSON input"
+  - "Error: Invalid JSON for parameter 'matrix': Unexpected end of JSON input"
+  - "Error: The expression result is not valid JSON"
+root_cause: |
+  fromJSON() is a GitHub Actions expression function that parses a JSON string.
+  When the input string is empty ("") — which happens when a step output was
+  never set or when the step that set it was skipped due to an if: condition —
+  fromJSON() throws a fatal parse error: "Unexpected end of JSON input".
+
+  This is especially common in dynamic matrix strategies:
+
+    matrix:
+      include: ${{ fromJSON(steps.generate.outputs.matrix) }}
+
+  If the generate step was skipped (e.g., if: github.event_name == 'push'),
+  steps.generate.outputs.matrix evaluates to empty string, and fromJSON("")
+  crashes the entire job before any steps run.
+
+  The expression evaluator does NOT treat empty string as null or as valid
+  empty JSON — it passes the raw empty string directly to the JSON parser,
+  which rejects it immediately.
+fix: |
+  Provide a fallback JSON value using the || operator so that fromJSON always
+  receives valid JSON even when the output is empty:
+
+    fromJSON(steps.generate.outputs.matrix || '[]')
+    fromJSON(steps.generate.outputs.config || '{}')
+
+  For dynamic matrix strategies, also ensure the generating step always
+  outputs valid JSON (at minimum '[]' or '{}') rather than leaving the
+  output unset when there is nothing to process.
+
+  Add an if: condition on downstream jobs to skip entirely when the matrix
+  output is empty or equals the empty-array sentinel.
+fix_code:
+  - language: yaml
+    label: "Guard fromJSON with a valid JSON fallback using the || operator"
+    code: |
+      jobs:
+        compute-matrix:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.gen.outputs.matrix }}
+          steps:
+            - id: gen
+              run: |
+                # Always emit valid JSON — even when there is nothing to build
+                TARGETS=$(cat targets.json 2>/dev/null || echo '[]')
+                echo "matrix=$TARGETS" >> $GITHUB_OUTPUT
+
+        build:
+          needs: compute-matrix
+          if: ${{ needs.compute-matrix.outputs.matrix != '[]' }}
+          strategy:
+            matrix:
+              # fromJSON never sees empty string — falls back to []
+              include: ${{ fromJSON(needs.compute-matrix.outputs.matrix || '[]') }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Building ${{ matrix.target }}"
+  - language: yaml
+    label: "Inline fallback for dynamic matrix include"
+    code: |
+      strategy:
+        matrix:
+          include: ${{ fromJSON(needs.setup.outputs.matrix || '[{"env":"default"}]') }}
+prevention:
+  - "Always provide a valid JSON fallback: fromJSON(steps.x.outputs.val || '{}')"
+  - "Ensure output-producing steps always write a value even if it is an empty array or object"
+  - "Add if: conditions to skip downstream jobs entirely when the matrix output is empty"
+  - "Validate fromJSON expressions with an empty-output test scenario in a draft workflow"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson"
+    label: "GitHub Docs — fromJSON expression function"
+  - 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 using outputs"
+  - url: "https://github.com/orgs/community/discussions/26671"
+    label: "GitHub Community #26671 — fromJSON fails when output is empty string"

package/errors/yaml-syntax/if-bang-negation-yaml-tag.yml

@@ -0,0 +1,145 @@
+id: yaml-syntax-020
+title: "if: !cancelled() Triggers YAML Tag Parse Error — Must Quote or Use Expression Syntax"
+category: yaml-syntax
+severity: error
+tags:
+  - if-condition
+  - cancelled
+  - yaml-tag
+  - expression-syntax
+  - negation
+  - bang-operator
+  - always-run
+  - parse-error
+patterns:
+  - regex: "if:\\s*!(?:cancelled|failure|success|always)\\(\\)"
+    flags: "im"
+  - regex: "mapping values are not allowed here|did not find expected key|could not find expected"
+    flags: "i"
+  - regex: "yaml.*tag.*!\\w+|Unknown tag"
+    flags: "i"
+error_messages:
+  - "mapping values are not allowed here"
+  - "could not find expected ':'"
+  - "did not find expected key"
+  - "Error: YAMLException: bad indentation of a mapping entry"
+  - "Invalid workflow file: You have an error in your yaml syntax"
+root_cause: |
+  In YAML, `!` is a reserved indicator used to specify **explicit type tags**
+  (e.g., `!!str`, `!python/object`). When you write an unquoted `if:` value starting
+  with `!`, the YAML parser interprets it as a tag application — NOT as boolean negation.
+
+  For example:
+  ```
+  if: !cancelled()   # YAML reads this as: apply tag "cancelled()" to null value
+  ```
+
+  Because `!cancelled()` is an invalid YAML tag application (no value follows the tag,
+  or the parentheses make it syntactically invalid as a tag identifier), this causes a
+  YAML parse error and the entire workflow file is rejected with messages like
+  "mapping values are not allowed here" or "bad indentation of a mapping entry".
+
+  This is a common mistake because developers familiar with programming languages expect
+  `!` to be a boolean NOT operator, which it is inside GitHub Actions expressions
+  (`${{ !cancelled() }}`), but NOT in bare YAML string values.
+
+  Affected operators:
+  - `if: !cancelled()` → YAML tag error
+  - `if: !failure()`   → YAML tag error
+  - `if: !success()`   → YAML tag error (rare, but same pattern)
+
+  The fix is either:
+  1. Wrap in expression delimiters: `if: ${{ !cancelled() }}`
+  2. Quote the value:             `if: "!cancelled()"`
+  Both forms are valid GitHub Actions `if:` conditions.
+
+  Source: GitHub Community Discussion — common YAML parse error with if: conditions
+  Source: GitHub Actions documentation — Expressions syntax
+fix: |
+  Choose one of two equivalent fixes:
+
+  Option 1 — Use expression syntax (recommended, more explicit):
+    `if: ${{ !cancelled() }}`
+
+  Option 2 — Quote the string (also valid):
+    `if: "!cancelled()"`
+
+  Both options tell the YAML parser to treat the value as a plain string / expression,
+  bypassing the tag interpretation.
+
+  Note: Inside `${{ }}` expression blocks, `!` IS the boolean NOT operator and works
+  as expected. Outside those blocks, bare YAML values starting with `!` are parsed as
+  YAML type tags.
+fix_code:
+  - language: yaml
+    label: "Fix: use ${{ }} expression syntax for negation"
+    code: |
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          steps:
+            # ❌ WRONG: YAML parse error — ! is a YAML tag indicator
+            - name: Run unless cancelled (broken)
+              if: !cancelled()
+              run: ./cleanup.sh
+
+            # ✅ CORRECT: wrap in expression delimiters
+            - name: Run unless cancelled (fixed)
+              if: ${{ !cancelled() }}
+              run: ./cleanup.sh
+
+            # ✅ ALSO CORRECT: quote the string
+            - name: Run unless cancelled (also fixed)
+              if: "!cancelled()"
+              run: ./cleanup.sh
+
+  - language: yaml
+    label: "Common patterns: negating status check functions"
+    code: |
+      jobs:
+        notify:
+          runs-on: ubuntu-latest
+          steps:
+            # Run step if previous steps did NOT fail
+            - name: Send success notification
+              if: ${{ !failure() }}
+              run: ./notify-success.sh
+
+            # Run if job was NOT cancelled (catch failures too)
+            - name: Always-ish cleanup (skips on cancel)
+              if: ${{ !cancelled() }}
+              run: ./cleanup.sh
+
+            # Job-level condition: run this job if parent was not skipped or failed
+            # (equivalent to always() but excluding explicitly-failed states)
+
+  - language: yaml
+    label: "Using always() instead of !cancelled() when appropriate"
+    code: |
+      jobs:
+        report:
+          runs-on: ubuntu-latest
+          # always() runs regardless of success, failure, OR cancellation
+          # !cancelled() runs on success OR failure, but NOT cancellation
+          steps:
+            - name: Report always (even if cancelled)
+              if: always()
+              run: ./post-report.sh
+
+            - name: Report unless cancelled
+              if: ${{ !cancelled() }}
+              run: ./post-report-unless-cancelled.sh
+
+prevention:
+  - "Always wrap boolean expressions using `!`, `&&`, or `||` inside `${{ }}` delimiters in `if:` conditions."
+  - "Quote any `if:` value that starts with `!` if you prefer not to use expression syntax."
+  - "Use `always()` when you want to run regardless of success, failure, AND cancellation."
+  - "Use `!cancelled()` (inside `${{ }}`) when you want to run on success or failure, but not cancellation."
+  - "Lint workflows with `actionlint` locally — it catches YAML tag parse errors before push."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#operators"
+    label: "GitHub Docs: Expressions — operators (! boolean NOT)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#status-check-functions"
+    label: "GitHub Docs: Expressions — status check functions (cancelled, failure, success)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif"
+    label: "GitHub Docs: Workflow syntax — steps.if"