badge

/auto-audit:badge — install README badges

You are installing two things on the currently-active audited repo:

1. A live status file at .auto-audit/status.json on a dedicated autoaudit/status branch. This is force-pushed by the plugin on every scan/merge so the shields.io endpoint badge reflects real state. It's not a PR — the plugin owns the branch.
2. A static "audited by auto-audit" badge in the target repo's README.md. This is opened as a normal PR the user can accept or close.

By default, do both. If the user passed --no-readme, skip the README PR and only publish the status branch.

Setup

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/common.sh"
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/state.sh"
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/git.sh"

SLUG="$(active_slug)" || { echo "no active auto-audit; run /auto-audit:start first" >&2; exit 1; }
with_lock "$SLUG"
WORKSPACE="$(workspace_dir)"

NO_README=0
case "${1:-}" in --no-readme) NO_README=1 ;; esac

Step 1 — publish the status branch

Always do this. The status JSON reflects whatever the findings queue looks like right now — empty queue = clean badge, pending findings = N findings badge, confirmed critical = critical badge.

STATUS_JSON="$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/status-json.sh")"
publish_status_branch "$STATUS_JSON"
iterations_append "badge_status_published" "" "$(echo "$STATUS_JSON" | jq -c '.message, .color | tostring' | paste -sd' ')"
echo "published status: $(echo "$STATUS_JSON" | jq -r .message) ($(echo "$STATUS_JSON" | jq -r .color))"

The shields.io URL the user puts in their README:

https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2F<OWNER>%2F<REPO>%2Fautoaudit%2Fstatus%2F.auto-audit%2Fstatus.json

Print that URL to the user with <OWNER>/<REPO> filled in from config.json's .url.

Step 2 — open README-badge PR (unless --no-readme)

if [ "$NO_README" -eq 0 ]; then
  BRANCH="autoaudit/badge"
  # Refresh the workspace to the default branch before branching so we
  # don't trip guard_not_default_branch: we need to *leave* the default
  # branch for the edit.
  default="$(default_branch)"
  git -C "$WORKSPACE" fetch origin "$default" 1>&2
  git -C "$WORKSPACE" checkout "$default" 1>&2
  git -C "$WORKSPACE" reset --hard "origin/$default" 1>&2
  git -C "$WORKSPACE" branch -D "$BRANCH" 2>/dev/null || true
  git -C "$WORKSPACE" checkout -b "$BRANCH" 1>&2

  ensure_readme_badge
  rc=$?
  case "$rc" in
    0)
      SHA="$(commit_all "badge" "docs: add auto-audit badge" "See https://auto-audit.hesketh.pro")"
      push_branch "$BRANCH"
      TITLE="docs: add auto-audit badge"
      BODY_FILE="$(mktemp)"
      cat > "$BODY_FILE" <<'EOF'
Adds a static badge to the README indicating this repo is audited by
[auto-audit](https://auto-audit.hesketh.pro). Decline this PR if you'd
rather not show the badge — the plugin will still work either way.

The companion **dynamic status badge** is available too. The plugin
publishes `.auto-audit/status.json` to the `autoaudit/status` branch on
every scan. Add this markdown snippet anywhere in your README to render
it (replace `OWNER/REPO`):

Colour follows severity:

- `auto-audit: clean` (green) — no open findings
- `auto-audit: N findings` (amber) — findings pending
- `auto-audit: critical` (red) — at least one confirmed critical

---

_Generated by the auto-audit plugin. See https://auto-audit.hesketh.pro ._
EOF
      PR_JSON="$(pr_open "$BRANCH" "$TITLE" "$BODY_FILE")"
      rm -f "$BODY_FILE"
      echo "README badge PR: $(echo "$PR_JSON" | jq -r .url)"
      iterations_append "badge_pr_opened" "" "$(echo "$PR_JSON" | jq -r .url)"
      ;;
    1) echo "README already has the badge — no PR needed" ;;
    2) echo "no README.md in target repo — skipping README badge (status branch still published)" ;;
  esac
fi

Output contract

End with a one-line summary the loop operator can read:

badge: status=<color> readme_pr=<url|skipped|already-present|no-readme>

Safety

• Never push outside autoaudit/* — publish_status_branch and push_branch both enforce this.
• Never commit on the target repo's default branch — commit_all refuses.
• The status branch is force-pushed on every update. That is intentional: it's a dedicated state branch the plugin owns, not user-authored content.
• If gh auth is missing or the user doesn't have write access to the target repo, the push will fail and the tick aborts cleanly.