feat(automerge): add safe-paths reusable for docs/tests-only PRs

[topcoder1]

Summary

A new reusable workflow that auto-enables gh pr merge --auto --squash on any PR (any author) whose diff touches only paths matching the safe list:

• docs/**
• tests/**
• test_*.py / *_test.{py,go,js,ts}
• *.test.{jsx,tsx,js,ts} / *.spec.{jsx,tsx,js,ts}
• **/__tests__/**

All-or-nothing: if even one changed file is outside the safe list, this workflow no-ops and downstream gating (claude-author-automerge, manual click) decides.

Rationale

Docs have zero runtime impact and tests can't break runtime — failing tests don't ship; passing tests don't change behavior. Maintainers click-merging typo fixes and test additions is alarm-fatigue-by-design. The path classification IS the safety argument.

This is a deliberate carve-out from the existing "human-authored PRs default to manual click-merge" policy. Sensitive surfaces (auth, secrets, migrations, workflows, infra) are still excluded — they don't match any of the safe globs, so this workflow leaves them to the existing gates.

Caller integration

# .github/workflows/safe-paths-automerge.yml in the caller repo
name: Safe-paths Auto-merge

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: safe-paths-automerge-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  automerge:
    uses: topcoder1/ci-workflows/.github/workflows/safe-paths-automerge.yml@main
    secrets: inherit
    with:
      merge_method: squash

Optional extra_safe_globs input lets callers extend the list per-repo (e.g. ^changelogs/.*, ^.devcontainer/.*).

Verification

• python3 yaml.safe_load parses; actionlint clean.
• Local smoke test against 7 diff scenarios:
  • docs-only → SAFE ✓
  • tests-only → SAFE ✓
  • mixed test layouts (Python + Go + JS + co-located) → SAFE ✓
  • docs + src → UNSAFE ✓
  • src-only → UNSAFE ✓
  • workflow file → UNSAFE ✓
  • src/.../test_*.py → SAFE (intentional — Python test convention)

Notes

• Auto-merge uses GitHub native gh pr merge --auto, so required-status-checks on the caller's branch-protection ruleset still apply. This workflow does not bypass branch protection.
• A bypass hole exists for production code named test_*.py (e.g. src/webcrawl/test_helpers.py). The Python convention is that test_*.py is always test code, but the workflow can't enforce that. Mitigation: existing CI build/lint/Claude-review still runs on every PR, so any production code accidentally classified as a test would still get reviewed.

Auto-merge rationale

Workflow file → manual click-merge per CLAUDE.md.

🤖 Generated with Claude Code

[claude]

No issues found. Logic is sound, failure modes are safe (loud fail, never silent bypass), and the known path-classification trade-off for Python test naming is clearly documented.