@htekdev/actions-debugger 1.0.22 → 1.0.24

package/errors/triggers/workflow-run-checkout-uses-default-branch.yml

@@ -0,0 +1,114 @@
+id: triggers-019
+title: "workflow_run-Triggered Job Checks Out Default Branch, Not the Triggering PR's Branch"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow_run
+  - checkout
+  - default-branch
+  - silent-failure
+  - pull-request
+
+patterns:
+  - regex: "workflow_run.*head_branch"
+    flags: "i"
+  - regex: "github\\.event\\.workflow_run\\.head_branch"
+    flags: "i"
+
+error_messages:
+  - "# No error message — the job silently runs against the wrong branch (e.g., main instead of the PR's feature branch)"
+  - "HEAD is now at <main-branch-commit> — expected feature branch content not present"
+
+root_cause: |
+  When a workflow is triggered via `workflow_run`, the triggered workflow ALWAYS
+  runs in the context of the repository's DEFAULT branch, not the branch that
+  caused the original workflow to run.
+
+  This means that `actions/checkout` without an explicit `ref:` will check out
+  the default branch (e.g., `main`), even when the triggering workflow ran on a
+  feature branch or PR. The job may silently pass because it's testing old code
+  on `main` rather than the developer's new changes.
+
+  This is by design: `workflow_run` is intended for privileged workflows that
+  run in the base repository context regardless of where the triggering push came
+  from. It avoids giving fork PRs access to secrets — but it also means the
+  checkout behavior surprises developers expecting to test branch code.
+
+  The branch of the triggering workflow IS available via the event context:
+    `github.event.workflow_run.head_branch`
+    `github.event.workflow_run.head_sha`
+
+fix: |
+  Explicitly set the `ref:` in your `actions/checkout` step to the triggering
+  workflow's head commit SHA or branch name.
+
+  Use `head_sha` (not `head_branch`) for more precise pinning — branch names
+  can advance between trigger and checkout for busy repositories.
+
+fix_code:
+  - language: yaml
+    label: "Checkout the triggering workflow's exact commit"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI — Unit Tests"]
+          types: [completed]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # Use head_sha for precise pinning — not head_branch
+                ref: ${{ github.event.workflow_run.head_sha }}
+
+  - language: yaml
+    label: "Download artifacts from the triggering workflow run instead of re-checking out"
+    code: |
+      # For deployment workflows, prefer downloading the build artifact
+      # from the triggering run rather than re-building from source.
+      # This avoids the branch checkout problem entirely.
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                run-id: ${{ github.event.workflow_run.id }}
+                name: build-output
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+            - name: Deploy
+              run: ./deploy.sh
+
+  - language: yaml
+    label: "Guard against running on wrong branch with a condition"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # Only deploy when triggered from the main branch to avoid
+          # accidentally deploying non-main code
+          if: |
+            github.event.workflow_run.conclusion == 'success' &&
+            github.event.workflow_run.head_branch == 'main'
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.workflow_run.head_sha }}
+
+prevention:
+  - "Always specify ref: ${{ github.event.workflow_run.head_sha }} in checkout steps inside workflow_run-triggered jobs."
+  - "Prefer downloading build artifacts over re-checking-out source code in workflow_run jobs to avoid branch confusion."
+  - "Log github.event.workflow_run.head_branch and head_sha at the start of workflow_run jobs for debugging."
+  - "Use the conclusion check (if: github.event.workflow_run.conclusion == 'success') to avoid deploying failed builds."
+
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run"
+    label: "GitHub Docs — workflow_run event"
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#using-data-from-the-triggering-workflow"
+    label: "GitHub Docs — Using data from the triggering workflow"
+  - url: "https://stackoverflow.com/questions/76184351"
+    label: "SO#76184351 — workflow_run job runs on wrong (default) branch"

package/errors/yaml-syntax/composite-action-run-shell-missing.yml

@@ -0,0 +1,90 @@
+id: yaml-syntax-030
+title: "Composite Action run: Step Missing Required shell: Property"
+category: yaml-syntax
+severity: error
+tags:
+  - composite-action
+  - shell
+  - required-property
+  - action-yml
+  - schema-validation
+patterns:
+  - regex: "Required property is missing: shell"
+    flags: "i"
+  - regex: "action\\.yml.*Required property is missing: shell"
+    flags: "i"
+error_messages:
+  - "Required property is missing: shell"
+  - "(Line: 29, Col: 5): Required property is missing: shell"
+  - "Error: GitHub.DistributedTask.ObjectTemplating.TemplateValidationException: The template is not valid."
+  - "Error: Fail to load action.yml"
+root_cause: |
+  Every run: step inside a composite action's action.yml MUST declare an explicit
+  shell: property. This is mandatory for composite actions — unlike regular workflow
+  run: steps where the runner infers the shell from the operating system, composite
+  action steps require an explicit declaration because the action may run on any OS.
+
+  The validation error fires at workflow preparation time (before any steps execute),
+  causing the entire workflow to fail with "Fail to load <action>.yml".
+
+  This is a common mistake when:
+  - Converting a workflow step into a reusable composite action
+  - Copying run: steps from a workflow into action.yml without adding shell:
+  - Using a third-party composite action whose author omitted the shell: property
+fix: |
+  Add shell: to every run: step in the composite action's action.yml.
+
+  Supported shell values: bash, sh, python, pwsh, powershell, cmd
+
+  For cross-platform composite actions, use shell: bash (available on all
+  GitHub-hosted runners including Windows via Git Bash). If platform-specific
+  behavior is needed, use if: runner.os == 'Windows' conditionals with
+  separate steps.
+fix_code:
+  - language: yaml
+    label: "Broken action.yml — run steps missing shell:"
+    code: |
+      runs:
+        using: "composite"
+        steps:
+          - name: Install dependencies
+            run: npm ci
+          - name: Run build
+            run: npm run build
+  - language: yaml
+    label: "Fixed action.yml — shell: added to every run step"
+    code: |
+      runs:
+        using: "composite"
+        steps:
+          - name: Install dependencies
+            run: npm ci
+            shell: bash
+          - name: Run build
+            run: npm run build
+            shell: bash
+  - language: yaml
+    label: "Cross-platform composite action with OS-conditional steps"
+    code: |
+      runs:
+        using: "composite"
+        steps:
+          - name: Run script (cross-platform)
+            run: echo "Running on ${{ runner.os }}"
+            shell: bash
+          - name: Windows-only step
+            if: runner.os == 'Windows'
+            run: Write-Host "Windows step"
+            shell: pwsh
+prevention:
+  - "Add actionlint to your CI — it catches missing shell: properties in composite actions."
+  - "When creating a new composite action, start from the GitHub documentation template which includes shell: on all run steps."
+  - "Every run: step in action.yml requires shell: — add this to code review checklists."
+  - "Use rhysd/actionlint locally or as a pre-commit hook to validate composite action syntax before pushing."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "GitHub Docs: Creating a composite action"
+  - url: "https://stackoverflow.com/questions/71041836/github-actions-required-property-is-missing-shell"
+    label: "Stack Overflow: Required property is missing: shell (Score: 51, 31K views)"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-actions"
+    label: "GitHub Docs: Metadata syntax for composite actions (runs.steps[*].shell)"

package/errors/yaml-syntax/composite-action-secrets-context-unavailable.yml

@@ -0,0 +1,99 @@
+id: yaml-syntax-025
+title: "secrets Context Unavailable Inside Composite Action Definitions"
+category: yaml-syntax
+severity: error
+tags:
+  - composite-actions
+  - secrets-context
+  - expression
+  - runner-validation
+  - context-availability
+  - action-yml
+patterns:
+  - regex: "Unrecognized named-value.*'?secrets'?"
+    flags: "i"
+  - regex: "Unexpected value.*secrets\\.\\w+"
+    flags: "i"
+error_messages:
+  - "Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.MY_TOKEN"
+  - "Error: Unrecognized named-value: 'secrets'"
+  - "Invalid workflow file: .github/actions/my-action/action.yml (Line 12, Col 18): Unrecognized named-value: 'secrets'"
+root_cause: |
+  The `secrets` context is **not available inside composite action definitions** (`action.yml`).
+  When a developer writes `${{ secrets.MY_TOKEN }}` inside a composite action's steps or
+  expressions, runner validation rejects it with "Unrecognized named-value: 'secrets'".
+
+  This is a deliberate architectural restriction. Composite actions run in the calling
+  workflow's runner environment but do NOT receive the calling workflow's secrets context.
+  The `secrets` context is only available in:
+  - Regular workflow job steps (`jobs.<job_id>.steps.*`)
+  - Reusable workflows (`.github/workflows/*.yml` using `on: workflow_call`)
+
+  Composite actions (`action.yml` with `using: composite`) only receive values the calling
+  workflow explicitly passes as `inputs`. This differs from `vars` context rejection
+  (yaml-syntax-016) — both contexts are unavailable in composite actions, but the pattern
+  for passing secrets as inputs is worth documenting separately.
+
+  A common migration mistake: extracting workflow steps that reference `${{ secrets.GITHUB_TOKEN }}`
+  into a composite action and expecting them to continue working unchanged.
+fix: |
+  Declare an explicit `input` for each secret the composite action needs. The calling workflow
+  passes secrets at the `with:` level — where the secrets context IS available. Inside the
+  composite action, reference `${{ inputs.token }}` instead of `${{ secrets.MY_TOKEN }}`.
+
+  Never reference the secrets context directly inside `action.yml` regardless of runner version.
+fix_code:
+  - language: yaml
+    label: "action.yml — Replace secrets.* with an explicit input"
+    code: |
+      # ❌ BROKEN: secrets context not available in composite actions
+      # .github/actions/deploy/action.yml
+      name: Deploy
+      description: Deploy to production
+      runs:
+        using: composite
+        steps:
+          - name: Authenticate
+            shell: bash
+            run: |
+              # ❌ Will fail: Unrecognized named-value: 'secrets'
+              echo "${{ secrets.DEPLOY_TOKEN }}" | docker login ghcr.io -u user --password-stdin
+
+      ---
+
+      # ✅ CORRECT: accept token via explicit input
+      name: Deploy
+      description: Deploy to production
+      inputs:
+        deploy-token:
+          description: "Authentication token for container registry"
+          required: true
+      runs:
+        using: composite
+        steps:
+          - name: Authenticate
+            shell: bash
+            run: echo "${{ inputs.deploy-token }}" | docker login ghcr.io -u user --password-stdin
+  - language: yaml
+    label: "Calling workflow — pass secrets at the with: level"
+    code: |
+      # ✅ Caller resolves secrets context and passes value as composite action input
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: ./.github/actions/deploy
+              with:
+                deploy-token: ${{ secrets.DEPLOY_TOKEN }}  # secrets resolved in caller, not in composite
+prevention:
+  - "Never reference `secrets.*` directly inside composite action `action.yml` — require callers to pass secrets as explicit inputs."
+  - "When migrating workflow steps to a composite action, replace every `${{ secrets.X }}` with a declared input and update all callers."
+  - "Use `actionlint` to statically validate context access in composite actions before pushing."
+  - "Composite actions (composite) require explicit input passing for secrets; reusable workflows (workflow_call) support `secrets: inherit`."
+docs:
+  - 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 by element type"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "GitHub Docs: Creating a composite action"
+  - url: "https://stackoverflow.com/questions/73821801/unable-to-use-secrets-in-workflow"
+    label: "SO#73821801 — Unrecognized named-value: 'secrets' in composite action (3,059 views)"

package/errors/yaml-syntax/github-script-octokit-renamed-to-github.yml

@@ -0,0 +1,130 @@
+id: yaml-syntax-026
+title: "actions/github-script: 'octokit' Not Defined — API Client Renamed to 'github'"
+category: yaml-syntax
+severity: error
+tags:
+  - github-script
+  - octokit
+  - javascript
+  - api-client
+  - breaking-change
+  - v4
+patterns:
+  - regex: "ReferenceError: octokit is not defined"
+    flags: "i"
+  - regex: "octokit is not defined"
+    flags: "i"
+  - regex: "TypeError: Cannot read propert(?:y|ies) of undefined.*octokit"
+    flags: "i"
+  - regex: "Error: Unhandled error: ReferenceError: octokit is not defined"
+    flags: "i"
+error_messages:
+  - "ReferenceError: octokit is not defined"
+  - "Error: Unhandled error: ReferenceError: octokit is not defined"
+  - "Error: Script failed with exit code 1 — ReferenceError: octokit is not defined"
+root_cause: |
+  In versions of `actions/github-script` prior to v4, the Octokit REST client
+  was injected into the script as a variable named `octokit`. The action was
+  refactored and the variable was renamed to `github` in v4 (released late 2020).
+
+  Many blog posts, Stack Overflow answers, older README examples, and community
+  discussions still use the original `octokit` variable name. Developers copying
+  these examples encounter `ReferenceError: octokit is not defined` at runtime
+  because the variable no longer exists.
+
+  Available variables injected into `actions/github-script` scripts (v4+):
+  - `github`   — authenticated Octokit REST + GraphQL client (replaces old `octokit`)
+  - `context`  — workflow run context (repo, sha, ref, event payload, etc.)
+  - `core`     — @actions/core (setOutput, setFailed, info, warning, etc.)
+  - `glob`     — @actions/glob (file globbing utility)
+  - `io`       — @actions/io (filesystem utilities)
+  - `exec`     — @actions/exec (run shell commands from script)
+  - `require`  — restricted require() for loading bundled modules
+
+  The variable `octokit` does not exist in any released version of
+  actions/github-script. It was never a stable public interface — the README
+  always showed `github`, but pre-release/alpha samples used `octokit`.
+
+  A secondary version of this error occurs with `github.rest` vs `github` API
+  surface: in v6+, REST methods moved to `github.rest.*` (e.g.,
+  `github.rest.issues.create()`). Scripts using `github.issues.create()` (v5
+  style) will fail with "TypeError: github.issues.create is not a function"
+  on v6+.
+fix: |
+  Replace every occurrence of `octokit` in your script with `github`:
+
+    Before (broken):  const result = await octokit.rest.issues.create({...})
+    After (correct):  const result = await github.rest.issues.create({...})
+
+  If you are using an older API surface (pre-v6), also update method paths:
+    Before (v5):  await github.issues.create({...})
+    After (v6+):  await github.rest.issues.create({...})
+
+  Check your github-script version — v6 is the current stable release (v7 is
+  also available with Node.js 20). Pin to a major version like @v7 rather than
+  a commit SHA to get bugfixes without breaking changes.
+fix_code:
+  - language: yaml
+    label: "Before (broken) vs After (correct) — replace octokit with github"
+    code: |
+      # BROKEN — uses old `octokit` variable name (throws ReferenceError):
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: issue } = await octokit.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Automated issue',
+              body: 'Created by workflow'
+            });
+
+      # CORRECT — use `github` (the injected Octokit client):
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: issue } = await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Automated issue',
+              body: 'Created by workflow'
+            });
+            console.log('Created issue #' + issue.number);
+  - language: yaml
+    label: "Common github-script v5 to v6+ migration — update method paths"
+    code: |
+      # v5 style (broken on v6+):
+      - uses: actions/github-script@v6
+        with:
+          script: |
+            await github.issues.addLabels({       # BROKEN: no github.issues
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: ['bug']
+            });
+
+      # v6+ style (correct):
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.addLabels({  # CORRECT: github.rest.*
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: ['bug']
+            });
+prevention:
+  - "Always use `github` (not `octokit`) as the Octokit client variable in actions/github-script — `octokit` has never been a stable public interface."
+  - "Pin to a major version like `actions/github-script@v7` rather than copying scripts from undated blog posts or old Stack Overflow answers that may reference pre-release variable names."
+  - "Test scripts locally using the `@octokit/rest` npm package before embedding them in a workflow — you'll get clear errors immediately rather than waiting for a CI run."
+  - "Read the actions/github-script README for your pinned version — the variable reference table at the top shows exactly what is injected (github, context, core, glob, io, exec)."
+  - "When upgrading from github-script v5 to v6+, update all REST method calls from `github.X.Y()` to `github.rest.X.Y()` — this is the only breaking change between v5 and v6."
+docs:
+  - url: "https://github.com/actions/github-script"
+    label: "actions/github-script README — available variables (github, context, core, etc.)"
+  - url: "https://github.com/actions/github-script/issues/545"
+    label: "actions/github-script #545: octokit instance from README examples doesn't work (12 reactions)"
+  - url: "https://github.com/actions/github-script/releases/tag/v4.0.0"
+    label: "actions/github-script v4 release — renamed octokit → github"
+  - url: "https://octokit.github.io/rest.js/v21"
+    label: "Octokit REST.js v21 API reference — methods available via github.rest.*"

package/errors/yaml-syntax/labeler-v5-config-format-breaking.yml

@@ -0,0 +1,67 @@
+id: yaml-syntax-028
+title: "actions/labeler v5 config format breaking change causes unexpected type error"
+category: yaml-syntax
+severity: error
+tags:
+  - labeler
+  - v5-breaking-change
+  - config-format
+  - pull-request-labels
+  - migration
+patterns:
+  - regex: "found unexpected type for label '.+' \\(should be array of config options\\)"
+    flags: "i"
+  - regex: "Error: found unexpected type for label"
+    flags: "i"
+error_messages:
+  - "Error: found unexpected type for label 'frontend' (should be array of config options)"
+  - "found unexpected type for label 'X' (should be array of config options)"
+root_cause: |
+  actions/labeler v5.0.0 introduced a breaking change to the labeler.yml configuration format.
+  In v4 and earlier, labels could be configured as a flat list of glob patterns (strings).
+  In v5, each label must be an array of objects with specific keys such as changed-files,
+  head-branch, or base-branch. If a workflow pins to @master or @latest and a new major
+  version is published, workflows inherit the breaking format without warning.
+  The old flat string format ("label: - path/**") is no longer valid in v5 and causes
+  the action to throw immediately.
+fix: |
+  Either migrate labeler.yml to the v5 object format using changed-files key, or pin the
+  action to @v4 to preserve the old flat string format.
+fix_code:
+  - language: yaml
+    label: "Old v4 format (still works with actions/labeler@v4)"
+    code: |
+      # .github/labeler.yml (v4 format)
+      frontend:
+        - shared/frontend/**/*
+      backend:
+        - shared/api/**/*
+  - language: yaml
+    label: "New v5 format (required for actions/labeler@v5)"
+    code: |
+      # .github/labeler.yml (v5 format)
+      frontend:
+        - changed-files:
+          - any-glob-to-any-file: shared/frontend/**/*
+      backend:
+        - changed-files:
+          - any-glob-to-any-file: shared/api/**/*
+  - language: yaml
+    label: "Pin to v4 to avoid breaking change"
+    code: |
+      steps:
+        - uses: actions/labeler@v4
+          with:
+            repo-token: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Never pin actions to @master or @latest branch — always use a major version tag like @v4"
+  - "Review the CHANGELOG or release notes before bumping a major version of any action"
+  - "Use Dependabot with major version grouping to get explicit upgrade PRs for breaking changes"
+  - "Test label config changes in a fork or draft PR before merging"
+docs:
+  - url: "https://github.com/actions/labeler/issues/710"
+    label: "actions/labeler#710: found unexpected type for label (v5 breaking change)"
+  - url: "https://github.com/actions/labeler/releases/tag/v5.0.0"
+    label: "actions/labeler v5.0.0 release notes"
+  - url: "https://github.com/actions/labeler/tree/main#pull-request-labeler"
+    label: "actions/labeler v5 configuration documentation"

package/errors/yaml-syntax/reusable-workflow-nesting-depth-exceeded.yml

@@ -0,0 +1,113 @@
+id: yaml-syntax-024
+title: "Reusable Workflow Nesting Exceeds Maximum Depth of 4 Levels"
+category: yaml-syntax
+severity: error
+tags:
+  - reusable-workflow
+  - nesting
+  - depth-limit
+  - workflow_call
+  - yaml-parse-error
+
+patterns:
+  - regex: "would exceed the limit on called workflow depth of \\d+"
+    flags: "i"
+  - regex: "calls workflow .+, but doing so would exceed the limit"
+    flags: "i"
+
+error_messages:
+  - "error parsing called workflow \"./.github/workflows/deploy.yml@\": job \"build\" calls workflow \"./.github/workflows/release.yml@\", but doing so would exceed the limit on called workflow depth of 3"
+  - "but doing so would exceed the limit on called workflow depth of 3"
+
+root_cause: |
+  GitHub Actions enforces a maximum reusable workflow call depth of 4 levels total.
+  The top-level workflow counts as level 1, so the maximum number of sequential
+  workflow_call hops is 3 (levels 2, 3, and 4).
+
+  The error message says "depth of 3" because it refers to the maximum allowed
+  zero-indexed depth of called workflows, not the total chain length.  When your
+  chain would require a 4th call (fifth total workflow), GitHub rejects the YAML
+  at parse time — before any runner picks up the job.
+
+  Example chain that fails:
+    root.yml → a.yml → b.yml → c.yml → d.yml   (depth index 4 → rejected)
+
+  Example chain that succeeds:
+    root.yml → a.yml → b.yml → c.yml            (depth index 3 → allowed)
+
+  This limit was increased from 2 to 3 in August 2022 and is currently fixed at 4
+  total levels (depth index 0–3).
+
+fix: |
+  Reduce the nesting depth so the total chain is 4 levels or fewer.
+  Strategies:
+
+  1. Flatten: merge two deeply-nested reusable workflows into one.
+  2. Convert inner reusables to composite actions — composite actions do NOT
+     count toward the reusable workflow depth limit.
+  3. Restructure so leaf workflows are composite actions, keeping reusable
+     workflows only at the top layers.
+
+fix_code:
+  - language: yaml
+    label: "Replace inner reusable workflow with a composite action"
+    code: |
+      # Instead of calling another reusable workflow at depth 4,
+      # use a composite action in .github/actions/my-task/action.yml
+      # which has no depth limit.
+
+      # .github/actions/my-task/action.yml
+      name: My Task
+      description: Previously a reusable workflow, now a composite action
+      runs:
+        using: composite
+        steps:
+          - name: Do the work
+            shell: bash
+            run: echo "doing the work"
+
+      # Called from the deeply-nested workflow:
+      - name: Run my task
+        uses: ./.github/actions/my-task  # composite, no depth counted
+
+  - language: yaml
+    label: "Flatten two reusable workflows into one to reduce depth"
+    code: |
+      # Before (depth 4 — fails):
+      # root.yml  →  build.yml  →  test.yml  →  lint.yml  →  scan.yml
+      #
+      # After (depth 3 — passes):
+      # Merge lint.yml and scan.yml into a single quality.yml
+
+      # quality.yml
+      on:
+        workflow_call:
+          inputs:
+            target:
+              required: true
+              type: string
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "linting ${{ inputs.target }}"
+        scan:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "scanning ${{ inputs.target }}"
+
+prevention:
+  - "Map your reusable workflow call chain before writing YAML — count total levels."
+  - "Prefer composite actions for leaf-level tasks; they have no depth limit."
+  - "Limit reusable workflow use to high-value shared orchestration layers, not every step."
+  - "If depth 4 is genuinely required, consider splitting the pipeline into separate triggered workflows using workflow_run instead of nested workflow_call."
+
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/reusing-workflows#nesting-reusable-workflows"
+    label: "GitHub Docs — Nesting reusable workflows"
+  - url: "https://github.blog/changelog/2022-08-22-github-actions-improvements-to-reusable-workflows-2/"
+    label: "GitHub Changelog — Nesting increased to 4 levels (August 2022)"
+  - url: "https://github.com/actions/runner/issues/1797"
+    label: "actions/runner#1797 — Original depth-limit enhancement request"