From 132e4fe51db48e5ecf59fc90d9caeb46f662591f Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Thu, 11 Jun 2026 14:25:12 -0400
Subject: [PATCH] Document README badges, repo topics, and PR auto-labeler
 conventions (INFRA-56/57/70) (#14)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Capture the org conventions rolled out in the INFRA-47 hygiene pass:
- github-standards.md: static-only README badges (dynamic shields break on
  private repos; CI badge is member-only) and a lowercase-hyphenated repo
  topic vocabulary, both part of new-repo provisioning.
- cicd.md: the central inline-config reusable PR labeler — pull_request
  trigger, the three required caller permissions, no per-repo labeler.yml.
---
 cicd.md             | 23 +++++++++++++++++++++++
 github-standards.md | 19 +++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/cicd.md b/cicd.md
index 176a6ba..0d746ec 100644
--- a/cicd.md
+++ b/cicd.md
@@ -96,3 +96,26 @@ Always pass `node-version: "24"` to reusable workflows. Local dev uses Node 24 /
 - When working on an existing project that lacks one — flag it and add it as part of the current work
 
 A project is not production-ready without CI/CD.
+
+## PR Auto-Labeling
+
+Pull requests are auto-labeled org-wide by a reusable workflow in `.github`. The label rules live once, centrally, inside the reusable workflow itself (written to the runner at execution time), so each repo needs only a short caller and **no per-repo `labeler.yml`**:
+
+```yaml
+# .github/workflows/labeler.yml — the per-repo caller
+name: Labeler
+on:
+  pull_request:
+    branches: [main]
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+jobs:
+  label:
+    uses: Sea-Haven-Industries/.github/.github/workflows/callable-labeler.yaml@main
+```
+
+- The trigger is plain `pull_request`, not `pull_request_target`: private repos take no fork PRs, so the lower-privilege event is sufficient and avoids the pwn-request surface. Because `pull_request` runs the workflow from the merge commit, the Labeler check appears on the PR that first adds the caller — an absent or failed check means a missing permission, not expected behaviour.
+- The caller MUST grant all three permissions. Reusable-workflow permissions can only be downgraded from the caller, so omitting `issues: write` (needed to create labels that don't exist yet) or any other grant causes a silent `startup_failure`.
+- Adding the caller is part of new-repo provisioning.
diff --git a/github-standards.md b/github-standards.md
index adf9feb..e96c774 100644
--- a/github-standards.md
+++ b/github-standards.md
@@ -4,6 +4,7 @@
 
 - Default branch: `main`
 - Every repo gets a one-line description
+- Every repo gets standard topics and a README badge block (see below)
 - Default to `private` visibility for org repos
 - Dependabot alerts and security updates enabled on all active repos
 - Org-level defaults auto-enable alerts and security updates on new repos
@@ -95,6 +96,24 @@ updates:
 - No force push to `main`
 - No branch deletion for `main`
 
+## README Badges
+
+Every repo's README carries a small badge block immediately under the H1. Use **static** badges only — dynamic badges (for example shields.io `last-commit` or `open-issues`) query the public GitHub API and render broken on private repos.
+
+- **CI status:** the GitHub-native workflow badge (`.../actions/workflows/<ci-file>/badge.svg`), and only when a CI workflow exists. On private repos it renders only for logged-in org members — that is accepted.
+- **Stack:** two to four static shields.io badges for the language and IaC/runtime (Python / TypeScript / .NET, AWS SAM / CDK), plus a Slack badge when the repo integrates Slack.
+- Keep badges static so they never go stale; version-pinned badges drift.
+
+## Repository Topics
+
+Every repo gets a set of lowercase, hyphenated topics so the org is filterable by stack and purpose. Draw from a consistent vocabulary:
+
+- **Cloud / IaC:** `aws`, `sam`, `cdk`, `lambda`, `ec2`, `s3`, `cloudfront`
+- **Language:** `python`, `typescript`, `javascript`, `dotnet`, `react`, `nodejs`
+- **Integration / domain:** `slack`, `bedrock`, `ai`, `security`, `internal-tool`, `documentation`
+
+Set them with `gh repo edit <repo> --add-topic a,b,c`. Adding topics is part of new-repo provisioning, not a follow-up.
+
 ## Repo Hygiene
 
 - Delete feature branches after merge