Make workflow linting reliable for large inlined reusable workflows

[j7an]

dependency-safety.yml embeds a large Scan and report Bash block inline, as required by this repo's reusable-workflow architecture. That inline shape is intentional: reusable workflows cannot safely check out this repo's script files at runtime from consumer repos, so the workflow YAML carries the executable logic directly and check-inline-sync.sh verifies the embedded copies stay aligned with scripts/.

During review of #80, local validation exposed a separate tooling problem: default actionlint hangs on .github/workflows/dependency-safety.yml when its ShellCheck integration is enabled. The hang is reproducible on origin/main, so it is not caused by #80. actionlint without ShellCheck integration completes immediately, and direct ShellCheck against the extracted shell content also completes. The failure mode appears to be an interaction between actionlint's ShellCheck orchestration and the large inlined Scan and report block, not a workflow syntax error or ShellCheck analysis failure.

This matters because maintainers need a reliable local and CI validation story for workflow changes. A hanging lint command is worse than a normal lint failure: it creates uncertainty during review, encourages ad hoc timeouts, and makes it easy to confuse a pre-existing validation-tool limitation with a PR regression. The repo already has strong workflow-specific validation through Bats, inline-sync checks, and reusable-workflow caller-context linting; this issue is about making the optional/general workflow-linting layer explicit and dependable.

Preferred direction: add a repo-local wrapper or documented check command for workflow structure linting, rather than rewriting workflow behavior to satisfy a fragile tool path. The supported workflow-lint command should disable actionlint's ShellCheck and Pyflakes integrations for workflow YAML linting:

actionlint -shellcheck= -pyflakes= .github/workflows/*.yml

ShellCheck should then run separately on the source scripts or extracted workflow blocks where that signal is useful. That keeps each validation layer focused: actionlint checks workflow structure, repo-specific tests check reusable-workflow invariants, inline-sync checks embedded script drift, and ShellCheck checks shell content through a path that completes reliably.

The goal is not to rewrite dependency-safety.yml purely to satisfy one tool mode. Any change should preserve the existing reusable-workflow architecture and avoid weakening the inline-sync invariant. The desired outcome is a documented, repeatable validation path that catches workflow problems without hanging, and that makes clear how shell analysis is covered for the large embedded scripts.

Acceptance Criteria

• The repository provides a supported workflow-linting path that does not hang on .github/workflows/dependency-safety.yml.

• The supported workflow-linting path uses actionlint for workflow/YAML structure without relying on the hanging ShellCheck integration path.

• The documented command or wrapper includes the equivalent of:

  actionlint -shellcheck= -pyflakes= .github/workflows/*.yml

• Shell analysis, if included in the validation story, runs separately against source scripts or extracted workflow blocks where that signal is useful.

• The validation story distinguishes:

  • workflow/YAML structure linting,
  • reusable-workflow caller-context linting,
  • inline script synchronization,
  • shell-script/runtime behavior coverage.

• The issue is addressed without changing dependency-safety.yml runtime behavior solely as a workaround for the lint hang.

• Maintainers can run the recommended checks locally and get deterministic pass/fail results instead of an indefinitely running actionlint process.

• The guidance explains why default actionlint with ShellCheck integration is not currently a reliable signal for dependency-safety.yml.

• Existing required validation remains intact: Bats tests, inline-sync validation, and workflow-call linting are still part of the expected review path.

Out of Scope

• Replacing the inline-script architecture for reusable workflows.
• Refactoring dependency-safety.yml behavior for readability alone.
• Treating the pre-existing actionlint hang as a blocker for fix(safety): explicit fork-PR behavior for read-only tokens (#79) #80.
• Broad workflow security hardening unrelated to the lint hang.