From 5a24a8139eead7a20beabd1c99e1ab260a5cf4a5 Mon Sep 17 00:00:00 2001
From: Jonathan Haas <jonathan@haas.holdings>
Date: Tue, 28 Apr 2026 15:46:15 -0700
Subject: [PATCH] docs: add actions quota hygiene convention

---
 profile/GITHUB_ACTIONS_QUOTA.md | 63 +++++++++++++++++++++++++++++++++
 profile/README.md               |  1 +
 2 files changed, 64 insertions(+)
 create mode 100644 profile/GITHUB_ACTIONS_QUOTA.md

diff --git a/profile/GITHUB_ACTIONS_QUOTA.md b/profile/GITHUB_ACTIONS_QUOTA.md
new file mode 100644
index 0000000..ded6bf7
--- /dev/null
+++ b/profile/GITHUB_ACTIONS_QUOTA.md
@@ -0,0 +1,63 @@
+# GitHub Actions Quota Hygiene
+
+EvalOps repositories should keep CI evidence useful without letting GitHub
+Actions minute or artifact quotas block unrelated pull requests.
+
+## CodeQL
+
+Run CodeQL on `main`, on a weekly schedule, and through manual dispatch. For
+pull requests, scope CodeQL with `paths` so documentation, GitOps metadata, and
+workflow-only changes do not spend full multi-language analysis capacity.
+
+Recommended PR path set:
+
+```yaml
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/codeql.yml"
+      - "go.mod"
+      - "go.sum"
+      - "**/*.go"
+      - "package.json"
+      - "package-lock.json"
+      - "pnpm-lock.yaml"
+      - "yarn.lock"
+      - "bun.lock"
+      - "bun.lockb"
+      - "**/*.js"
+      - "**/*.jsx"
+      - "**/*.mjs"
+      - "**/*.cjs"
+      - "**/*.ts"
+      - "**/*.tsx"
+      - "pyproject.toml"
+      - "poetry.lock"
+      - "requirements*.txt"
+      - "**/*.py"
+```
+
+Keep the checked-in CodeQL workflow explicit. Do not rely on generated CodeQL
+runs when runner placement, matrix languages, or branch behavior matter.
+
+## Artifacts
+
+Every `actions/upload-artifact` step must set `retention-days`.
+
+Use short retention for diagnostics:
+
+- PR logs, flaky-test logs, coverage HTML, drift previews: `3` to `7` days.
+- Release candidate packages, SBOMs, promotion inventories: `7` to `14` days.
+- Audit evidence needed for compliance review: keep the documented compliance
+  retention window and make the degradation path explicit.
+
+Diagnostic uploads should use `continue-on-error: true` when the prior command
+already produced the gate result. Artifact quota exhaustion must not turn a
+passing coverage, lint, or drift check into a failed required status.
+
+## Runner Budget
+
+Prefer Blacksmith runners for normal CI unless a vendor workflow requires
+GitHub-hosted OIDC or trusted publishing. When a job stays on `ubuntu-latest`,
+leave a comment explaining the dependency so later runner migrations do not
+re-introduce quota or authentication failures.
diff --git a/profile/README.md b/profile/README.md
index 40b9ebd..37a2cf6 100644
--- a/profile/README.md
+++ b/profile/README.md
@@ -5,6 +5,7 @@ The organizational operating system for AI agent workforces — evaluation, gove
 ## Operating Conventions
 
 - [Agent authorship attribution](AGENT_AUTHORSHIP.md) — git trailers, PR labels, and audit indexing for Maestro-authored code.
+- [GitHub Actions quota hygiene](GITHUB_ACTIONS_QUOTA.md) — CodeQL scoping, artifact retention, and quota-safe diagnostics.
 
 ## Platform Services