From ddb07d579c81a1e1d6a36df3a98fd7e5c99d0de3 Mon Sep 17 00:00:00 2001 From: DJ Date: Sun, 5 Apr 2026 11:29:40 -0700 Subject: [PATCH 1/2] feat: audit .github repo and add CLAUDE.md/AGENTS.md checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove .github repo exclusion — it now gets audited like all other repos (settings, labels, rulesets, workflows, etc.) - Add check_claude_md: every repo must have a CLAUDE.md that references AGENTS.md - Add check_agents_md: every repo must have an AGENTS.md that references the org-level .github/AGENTS.md Co-Authored-By: Claude Opus 4.6 (1M context) --- scripts/compliance-audit.sh | 66 ++++++++++++++++++++++++++++++++----- 1 file changed, 58 insertions(+), 8 deletions(-) diff --git a/scripts/compliance-audit.sh b/scripts/compliance-audit.sh index c5e52da..497f967 100755 --- a/scripts/compliance-audit.sh +++ b/scripts/compliance-audit.sh @@ -401,6 +401,61 @@ check_workflow_permissions() { done } +# --------------------------------------------------------------------------- +# Check: CLAUDE.md exists and references AGENTS.md +# --------------------------------------------------------------------------- +check_claude_md() { + local repo="$1" + + local content + content=$(gh_api "repos/$ORG/$repo/contents/CLAUDE.md" --jq '.content' 2>/dev/null || echo "") + + if [ -z "$content" ]; then + add_finding "$repo" "standards" "missing-claude-md" "error" \ + "Missing \`CLAUDE.md\` — every repo must have a CLAUDE.md that references AGENTS.md" \ + "standards/github-settings.md" + return + fi + + local decoded + decoded=$(echo "$content" | base64 -d 2>/dev/null || echo "") + + if ! echo "$decoded" | grep -qi 'AGENTS\.md'; then + add_finding "$repo" "standards" "claude-md-missing-agents-ref" "warning" \ + "\`CLAUDE.md\` does not reference \`AGENTS.md\`" \ + "standards/github-settings.md" + fi +} + +# --------------------------------------------------------------------------- +# Check: AGENTS.md exists and references org .github/AGENTS.md +# --------------------------------------------------------------------------- +check_agents_md() { + local repo="$1" + + local content + content=$(gh_api "repos/$ORG/$repo/contents/AGENTS.md" --jq '.content' 2>/dev/null || echo "") + + if [ -z "$content" ]; then + add_finding "$repo" "standards" "missing-agents-md" "error" \ + "Missing \`AGENTS.md\` — every repo must have an AGENTS.md that references the org-level standards" \ + "standards/github-settings.md" + return + fi + + # For repos other than .github, AGENTS.md should reference the org-level .github/AGENTS.md + if [ "$repo" != ".github" ]; then + local decoded + decoded=$(echo "$content" | base64 -d 2>/dev/null || echo "") + + if ! echo "$decoded" | grep -qE '(\.github/AGENTS\.md|petry-projects/\.github)'; then + add_finding "$repo" "standards" "agents-md-missing-org-ref" "warning" \ + "\`AGENTS.md\` does not reference the org-level \`.github/AGENTS.md\` standards" \ + "standards/github-settings.md" + fi + fi +} + # --------------------------------------------------------------------------- # Issue management # --------------------------------------------------------------------------- @@ -585,7 +640,7 @@ HEREDOC HEREDOC - for category in ci-workflows action-pinning dependabot settings labels rulesets; do + for category in ci-workflows action-pinning dependabot settings labels rulesets standards; do local cat_count cat_count=$(jq --arg cat "$category" '[.[] | select(.category == $cat)] | length' "$FINDINGS_FILE") if [ "$cat_count" -gt 0 ]; then @@ -624,11 +679,6 @@ main() { local repo_count=0 for repo in $repos; do - # Skip the .github config repo itself (different compliance criteria) - if [ "$repo" = ".github" ]; then - continue - fi - repo_count=$((repo_count + 1)) log "Auditing $ORG/$repo" @@ -648,6 +698,8 @@ main() { check_codeowners "$repo" check_sonarcloud "$repo" check_workflow_permissions "$repo" + check_claude_md "$repo" + check_agents_md "$repo" log_end done @@ -662,8 +714,6 @@ main() { info "Managing issues..." for repo in $repos; do - [ "$repo" = ".github" ] && continue - ensure_audit_label "$repo" # Create issues for new findings (process substitution avoids subshell) From 58e86b929c18f358100dff19765731208ff351c0 Mon Sep 17 00:00:00 2001 From: DJ Date: Sun, 5 Apr 2026 11:38:11 -0700 Subject: [PATCH 2/2] fix: address review comments on CLAUDE.md/AGENTS.md checks - Point standard_ref to AGENTS.md (the actual source of truth) - Upgrade missing-ref severities from warning to error (required) - Tighten AGENTS.md org-ref grep to match .github/AGENTS.md only Co-Authored-By: Claude Opus 4.6 (1M context) --- scripts/compliance-audit.sh | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/scripts/compliance-audit.sh b/scripts/compliance-audit.sh index 497f967..93ba142 100755 --- a/scripts/compliance-audit.sh +++ b/scripts/compliance-audit.sh @@ -413,7 +413,7 @@ check_claude_md() { if [ -z "$content" ]; then add_finding "$repo" "standards" "missing-claude-md" "error" \ "Missing \`CLAUDE.md\` — every repo must have a CLAUDE.md that references AGENTS.md" \ - "standards/github-settings.md" + "AGENTS.md" return fi @@ -421,9 +421,9 @@ check_claude_md() { decoded=$(echo "$content" | base64 -d 2>/dev/null || echo "") if ! echo "$decoded" | grep -qi 'AGENTS\.md'; then - add_finding "$repo" "standards" "claude-md-missing-agents-ref" "warning" \ + add_finding "$repo" "standards" "claude-md-missing-agents-ref" "error" \ "\`CLAUDE.md\` does not reference \`AGENTS.md\`" \ - "standards/github-settings.md" + "AGENTS.md" fi } @@ -439,7 +439,7 @@ check_agents_md() { if [ -z "$content" ]; then add_finding "$repo" "standards" "missing-agents-md" "error" \ "Missing \`AGENTS.md\` — every repo must have an AGENTS.md that references the org-level standards" \ - "standards/github-settings.md" + "AGENTS.md" return fi @@ -448,10 +448,10 @@ check_agents_md() { local decoded decoded=$(echo "$content" | base64 -d 2>/dev/null || echo "") - if ! echo "$decoded" | grep -qE '(\.github/AGENTS\.md|petry-projects/\.github)'; then - add_finding "$repo" "standards" "agents-md-missing-org-ref" "warning" \ + if ! echo "$decoded" | grep -qE '\.github/AGENTS\.md'; then + add_finding "$repo" "standards" "agents-md-missing-org-ref" "error" \ "\`AGENTS.md\` does not reference the org-level \`.github/AGENTS.md\` standards" \ - "standards/github-settings.md" + "AGENTS.md" fi fi }