docs(ci): define phase-1 actions source allowlist policy (#405)

AGENTS.md

@@ -250,6 +250,7 @@ Use these rules to keep the trait/factory architecture stable under growth.
 - Include threat/risk notes and rollback strategy.
 - Add/update tests or validation evidence for failure modes and boundaries.
 - Keep observability useful but non-sensitive.
+- For `.github/workflows/**` changes, include Actions allowlist impact in PR notes and update `docs/actions-source-policy.md` when sources change.
 
 ## 8) Validation Matrix
 
@@ -378,6 +379,7 @@ Reference docs:
 - `docs/pr-workflow.md`
 - `docs/reviewer-playbook.md`
 - `docs/ci-map.md`
+- `docs/actions-source-policy.md`
 
 ## 10) Anti-Patterns (Do Not)
 

docs/actions-source-policy.md

@@ -0,0 +1,62 @@
+# Actions Source Policy (Phase 1)
+
+This document defines the current GitHub Actions source-control policy for this repository.
+
+Phase 1 objective: lock down action sources with minimal disruption, before full SHA pinning.
+
+## Current Policy
+
+- Repository Actions permissions: enabled
+- Allowed actions mode: selected
+- SHA pinning required: false (deferred to Phase 2)
+
+Selected allowlist patterns:
+
+- `actions/*` (covers `actions/cache`, `actions/checkout`, `actions/upload-artifact`, `actions/download-artifact`, and other first-party actions)
+- `docker/*`
+- `dtolnay/rust-toolchain@*`
+- `Swatinem/rust-cache@*`
+- `DavidAnson/markdownlint-cli2-action@*`
+- `lycheeverse/lychee-action@*`
+- `EmbarkStudios/cargo-deny-action@*`
+- `rhysd/actionlint@*`
+- `softprops/action-gh-release@*`
+
+## Why This Phase
+
+- Reduces supply-chain risk from unreviewed marketplace actions.
+- Preserves current CI/CD functionality with low migration overhead.
+- Prepares for Phase 2 full SHA pinning without blocking active development.
+
+## Agentic Workflow Guardrails
+
+Because this repository has high agent-authored change volume:
+
+- Any PR that adds or changes `uses:` action sources must include an allowlist impact note.
+- New third-party actions require explicit maintainer review before allowlisting.
+- Expand allowlist only for verified missing actions; avoid broad wildcard exceptions.
+- Keep rollback instructions in the PR description for Actions policy changes.
+
+## Validation Checklist
+
+After allowlist changes, validate:
+
+1. `CI`
+2. `Docker`
+3. `Security Audit`
+4. `Workflow Sanity`
+5. `Release` (when safe to run)
+
+Failure mode to watch for:
+
+- `action is not allowed by policy`
+
+If encountered, add only the specific trusted missing action, rerun, and document why.
+
+## Rollback
+
+Emergency unblock path:
+
+1. Temporarily set Actions policy back to `all`.
+2. Restore selected allowlist after identifying missing entries.
+3. Record incident and final allowlist delta.

docs/ci-map.md

@@ -76,6 +76,7 @@ Merge-blocking checks should stay small and deterministic. Optional checks are u
 
 - Keep merge-blocking checks deterministic and reproducible (`--locked` where applicable).
 - Prefer explicit workflow permissions (least privilege).
+- Keep Actions source policy restricted to approved allowlist patterns (see `docs/actions-source-policy.md`).
 - Use path filters for expensive workflows when practical.
 - Keep docs quality checks low-noise (`markdownlint` + offline link checks).
 - Keep dependency update volume controlled (grouping + PR limits).