docs: document actions pinning policy (#136)

Co-authored-by: CoderDeltaLAN <CoderDeltaLAN@users.noreply.github.com>

Author: CoderDeltaLAN

CHANGELOG.md

@@ -6,6 +6,7 @@ This project has a published GitHub Release line, but no stable support or API g
 
 ## [Unreleased]
 
+- Documented the GitHub Actions pinning policy decision before the v0.4.0 release train.
 - Refreshed the external audit package manifest and corrected pre-v0.4.0 readiness statuses after F-01.
 - Triaged superseded v0.3.1 release-target wording before the v0.4.0 release train.
 - Add non-UTF-8 error-contract coverage for `dedupe` and `conflicts`.

docs/ACTIONS-PINNING-POLICY.md

@@ -0,0 +1,63 @@
+# GitHub Actions Pinning Policy
+
+Status: accepted policy decision.
+Scope: GitHub Actions workflow references for this repository.
+Current phase: policy decision only; no workflow action references are changed here.
+
+## Decision
+
+agent-rules-kit accepts full-length commit SHA pinning as the stricter long-term supply-chain policy for GitHub Actions.
+
+The implementation is intentionally separated from this documentation phase. Action references must not be converted by string replacement or broad automation. Each action must preserve its full repository path, including sub-actions such as github/codeql-action/init and github/codeql-action/analyze.
+
+## Why this policy exists
+
+GitHub's security guidance states that pinning an action to a full-length commit SHA is currently the only way to use an action as an immutable release.
+
+The same guidance also notes that tag-based references are more convenient and common, but tags can move or be deleted if an action repository is compromised.
+
+This project currently uses explicit version tags for trusted actions. That is acceptable as a transitional state, not as the final strictest policy.
+
+## Required implementation rules
+
+A future implementation phase must:
+
+- use a dedicated branch;
+- update only workflow action references and the local audit inventory needed to verify them;
+- verify each SHA belongs to the canonical action repository, not a fork;
+- preserve sub-action paths exactly;
+- keep workflow permissions minimal;
+- run local checks before stage;
+- stage exact files only;
+- run a strong pre-push before push;
+- verify PR checks and main checks by exact SHA;
+- document the update path for future Dependabot or manual refreshes.
+
+## Prohibited implementation shortcuts
+
+Do not:
+
+- rewrite action references with blind regex replacement;
+- collapse sub-actions such as github/codeql-action/init into github/codeql-action;
+- invent SHAs;
+- copy SHAs from unofficial sources;
+- combine pinning with release, PyPI, README final, dependency changes, branch protection, Scorecard, CodeQL, or product behavior;
+- describe SHA pinning as a security guarantee.
+
+## Current workflow references
+
+Current transitional references:
+
+- actions/checkout@v7
+- actions/setup-python@v6
+- github/codeql-action/init@v4
+- github/codeql-action/analyze@v4
+- actions/upload-artifact@v4
+- actions/download-artifact@v8
+- pypa/gh-action-pypi-publish@release/v1
+
+## Release-train impact
+
+For v0.4.0, this policy closes the decision gap.
+
+The actual conversion to full-length SHA pinning remains a separate supply-chain implementation phase and must not be rushed into a release branch without exact repository/SHA verification and a clean Always-Green run.

docs/SECURITY-SUPPLY-CHAIN-EVALUATION.md

@@ -129,24 +129,27 @@ Recommended future Scorecard phase boundary:
 
 ## GitHub Actions pinning policy
 
-The workflows currently use version tags such as `actions/checkout@v7`, `actions/setup-python@v6`, `actions/upload-artifact@v4`, `actions/download-artifact@v8`, and `pypa/gh-action-pypi-publish@release/v1`.
+The workflows currently use version tags such as `actions/checkout@v7`, `actions/setup-python@v6`, `github/codeql-action/init@v4`, `github/codeql-action/analyze@v4`, `actions/upload-artifact@v4`, `actions/download-artifact@v8`, and `pypa/gh-action-pypi-publish@release/v1`.
 
-Potential stronger policy:
+Current policy decision:
 
-- pin third-party actions by full commit SHA;
-- document how pinned actions are reviewed and updated.
+- full-length commit SHA pinning is accepted as the stricter long-term GitHub Actions supply-chain policy;
+- the current tag-based references are a transitional state, not the final strictest policy;
+- the policy and implementation guardrails are documented in `docs/ACTIONS-PINNING-POLICY.md`.
 
 Risks and constraints:
 
 - full SHA pinning improves immutability but increases update burden;
 - a partial or stale pinning policy can create false confidence;
-- changing action references must be its own CI/supply-chain phase.
+- changing action references must be its own CI/supply-chain implementation phase;
+- sub-actions such as `github/codeql-action/init` and `github/codeql-action/analyze` must preserve their full path when pinned.
 
 Decision for this phase:
 
-- do not change action references here;
+- do not change workflow action references here;
 - keep current explicit permissions;
-- evaluate action pinning in a separate phase if the maintainer wants stricter supply-chain hardening.
+- record the accepted policy and exact implementation guardrails;
+- defer actual SHA conversion to a dedicated implementation phase with exact repository/SHA verification.
 
 ## Decision