docs: document local actionlint validation

Author: coisa

.agents/agents/review-guardian.md

@@ -27,8 +27,9 @@ and generated-output drift before human review time is spent.
   surfaces when touched.
 - Require explicit validation evidence for workflow, local-action, and
   packaged-wrapper changes. Prefer deterministic local harnesses, fake
-  ``gh``/``git`` scripts, temporary repositories, shell/YAML checks, or a
-  temporary validation PR when GitHub-only behavior cannot be exercised locally.
+  ``gh``/``git`` scripts, temporary repositories, ``actionlint`` for workflows,
+  shell/YAML checks, or a temporary validation PR when GitHub-only behavior
+  cannot be exercised locally.
 - When a workflow pushes commits with ``GITHUB_TOKEN``, verify that required
   checks are dispatched or mirrored for the bot-authored commit before treating
   the workflow as safe.

.agents/skills/pull-request-review/references/workflow-action-validation.md

@@ -45,7 +45,7 @@ Validation Strategies
 Prefer deterministic local validation when it can cover the changed behavior:
 
 - run ``bash -n`` for shell scripts;
-- parse changed YAML files or run ``actionlint`` when available;
+- parse changed YAML files or run ``actionlint`` after ensuring it is available;
 - use fake ``gh`` and ``git`` wrappers to exercise action scripts without
   calling GitHub;
 - create temporary Git repositories to validate merge, rebase, conflict,
@@ -54,6 +54,34 @@ Prefer deterministic local validation when it can cover the changed behavior:
 - verify packaged wrapper inputs, permissions, and reusable workflow paths stay
   aligned with the canonical workflow.
 
+Actionlint Availability
+-----------------------
+
+When workflow files are changed, prefer running ``actionlint`` locally. If it is
+missing, install it before review when the platform has a safe package manager:
+
+- macOS with Homebrew: ``brew install actionlint``;
+- macOS with MacPorts: ``sudo port install actionlint``;
+- Debian-based Linux: download the official ``actionlint`` release archive for
+  the host architecture, unpack the binary into a temporary directory, and run
+  it from there or install it into a user-local ``PATH`` such as
+  ``~/.local/bin``.
+
+``actionlint`` is distributed as a Go binary. It may use ``shellcheck`` for
+``run:`` blocks, and Homebrew installs that dependency automatically. On
+Windows, prefer WSL for now unless the repository already documents a native
+Windows installation path.
+
+Use the broadest relevant command for the changed surfaces, for example:
+
+.. code-block:: bash
+
+   actionlint .github/workflows/*.yml resources/github-actions/*.yml
+
+Record the command and result in the review evidence. If installation is not
+possible, record that as a residual validation gap instead of silently skipping
+workflow linting.
+
 When local simulation cannot cover the behavior, call out the gap and prefer a
 temporary validation branch or pull request. Close that validation PR after
 recording the evidence in the real PR or issue. Do not require noisy temporary

CHANGELOG.md

@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Auto-resolve pull-request conflicts limited to workflow-managed `.github/wiki` pointers and `CHANGELOG.md` `Unreleased` drift (#192)
-- Teach the pull-request review skill, review-guardian agent, and review request brief to require explicit validation strategies for workflow, local-action, and packaged-wrapper changes (#241)
+- Teach the pull-request review skill, review-guardian agent, and review request brief to require explicit validation strategies for workflow, local-action, and packaged-wrapper changes, including local `actionlint` installation guidance (#241)
 
 ### Fixed