Repository navigation
Description
Why
Public org repos accept PRs from anyone. Today spam and low-effort outside PRs sit open until a maintainer notices them (the stale-manager window is ~37 days), attract third-party bot noise (Qodo, CodeRabbit, cubic), and consume maintainer attention. The motivating incident is petry-projects/.github-private#1976 (2026-09-29): a name-as-title, unfilled-template, typo-introducing PR from a brand-new FIRST_TIME_CONTRIBUTOR. Nothing in our automation acted on it, and the existing description-quality check was fooled — a naive keyword grep over the raw body matches the template's own headings and HTML comments, so an empty template scored 0/5 missing sections.
What — a fleet-vendored capability on the org-standard shape
spam-pr-guard ships as a reusable workflow hosted in petry-projects/.github and consumed by every org repo via a thin caller stub that pins the per-agent canary channel. This matches how pr-auto-review, persona-mention, agent-shield, add-to-project, and the other first-party capabilities already ship — see standards/ci-standards.md § Reusable workflow versioning and standards/canary-rings.json.
Layered defense (layer scope unchanged; delivery shape realigned)
- Layer 0 (native, no code): GitHub-native controls — require workflow approval for outside contributors; per-repo PR caps with a bypass list. Phase 0.
- Layer 1 (
spam-pr-guard): a Class-1,pull_request_target, metadata-only reusable workflow that runs a deterministic (no-LLM) scorer and maps a PR to low / medium (needs-infolabel + comment) / high (spamlabel + close). Shippeddry_run: truefirst;dry_runis a stub input, defaulting ON so consumers can flip it per-repo as the canary advances. Phases 1–3. - Layer 2: fix the description-quality check so an unfilled template is no longer read as complete. Phase 1 — delivered as
scripts/lib/safety-checks.sh::sc_description_missing, a sourceable helper the scorer calls. - Layer 3: a short stale window for unanswered
needs-infooutside PRs, plus weekly reporting to tune thresholds. Phase 6.
Delivery shape (vendored from .github, consumed by stub, released on canary tags)
| Artifact | Path in petry-projects/.github |
Role |
|---|---|---|
| Reusable workflow | .github/workflows/spam-pr-guard-reusable.yml |
on: workflow_call: entry point. inputs.dry_run (bool, default true), inputs.agent_ref (string, default spam-pr-guard/v1-stable). permissions: {} top-level; job-level grants only what the layer actually writes. Checks out petry-projects/.github@${{ inputs.agent_ref }} to source scripts/lib/safety-checks.sh + scripts/spam-pr-score.sh at the pinned channel. Pattern: .github/workflows/add-to-project-reusable.yml:62-99. |
| Scorer | scripts/spam-pr-score.sh |
Deterministic signal → score mapper. Phase 2. |
| Safety-checks lib | scripts/lib/safety-checks.sh |
sc_description_missing + future sc_* signals. Phase 1 (PR #1218 in flight). |
| Caller stub (template) | standards/workflows/spam-pr-guard.yml |
Thin stub emitted by scripts/seed-repo-template.sh into each consumer. Pins uses: petry-projects/.github/.github/workflows/spam-pr-guard-reusable.yml@spam-pr-guard/v1-stable # NOSONAR(githubactions:S7637) first-party channel ref (the NOSONAR marker is mandatory; seed-repo-template.sh:60-67 fails closed without it). Passes with: { dry_run: true, agent_ref: spam-pr-guard/v1-stable }. Shape mirrors standards/workflows/pr-auto-review.yml:1-81. |
| Paired tests workflow | .github/workflows/spam-pr-guard-tests.yml |
Path-filtered bats + shellcheck; triggers on changes to the reusable, scripts, tests, fixtures, and the stub. Model: .github/workflows/pr-auto-review-tests.yml. |
| User-facing standard | standards/spam-pr-guard.md (dedicated file; or new section in standards/ci-standards.md if scope stays small) |
Signal table, action mapping, config knobs, security invariant, false-positive appeal path. Ships automatically on the next scripts/cut-standards-release.sh cut vX.Y.Z → standards/v1-stable. Phase 4. |
| Interaction contract | interaction-contracts/spam-pr-guard.yml + row in docs/agentic-interaction-model.md §4 |
Class-1, metadata-only invariant, budget: none. Phase 3. |
| Registry entry | standards/canary-rings.json .agents["spam-pr-guard"] |
host: petry-projects/.github, reusable: .github/workflows/spam-pr-guard-reusable.yml, run_workflow: <caller-stub display name>, standard #548 gate, rings next → ring0 → ring1 → stable. Phase 3. |
| Deploy wiring | scripts/deploy-standard-workflows.sh DEPLOYABLE_WORKFLOWS=(...) (lines 116-129) + SKIP_SELF_MANAGED entries for .github/.github-private where appropriate |
Live propagation of the stub to existing repos. Phase 3. |
| Ring-pins wiring | scripts/lib/ring-pins.sh RING_REUSABLES=(...) (lines 32-50) |
Alphabetical insertion; bats asserts equality to `.agents |
Canary rings (fleet default; dogfood at the source)
Per the registry pattern (standards/canary-rings.json lines 20–55 for dev-lead, 949–1017 for pr-auto-review):
next→petry-projects/.github-private(dogfood at the source —pr-auto-review,persona-mention,agent-shield, etc. all routenextthrough.github-private).ring0→petry-projects/.github(this repo).ring1→petry-projects/TalkTerm,petry-projects/bmad-bgreat-suite.stable→*(every other consumer).require_confirmation: trueonring1→stableso the human go/no-go to enable label/close ships through the fleet rather than through a code flip (Phase 5).
Promotion is automatic through the registry's graduated dwell/sample gate (scripts/canary-rollout.sh); canary-rollout.sh autocut cuts spam-pr-guard/vX.Y.Z from the host-main-HEAD blob + agent_ref_paths (default [scripts/, prompts/, personas/]) and moves the next channel.
Success metrics (initiative-level, measurable)
- Median time-to-close for spam outside PRs: from ~37 days (stale-manager) to < 24h.
- False-positive rate (legitimate PRs auto-closed): < 2% of auto-closes.
- Reopened-after-auto-close rate: tracked, target < 5%.
- Zero false positives on legitimate first-time PRs during the DRY_RUN soak on
next+ring0, validated against >= 10 real outside-PR events. - Third-party bot noise on spam PRs driven to near zero (closed before bots react).
Cost cap / budget bound
The spam-pr-guard reusable is deterministic and adds zero incremental LLM spend — it invokes no engine (contrast scripts/stale-manager.sh, which calls Claude). It is event-driven only (pull_request_target, no schedule, no polling) and runs at most once per PR open/edit/reopen event; staged actions are idempotent (one marker-keyed comment per PR). Fork PRs never reach agents (no secrets), so there is no agent-churn budget to bound; the workflow declares budget: none in its interaction contract with that justification.
Safety
The scorer is metadata-only with no PR-code execution (validated by actions/checkout v7 defaults that block fork checkout in pull_request_target), fails closed (an unreadable signal escalates to a human, never scores "not spam"), and never self-triggers (§7 rule 1). Automation never blocks users; the live-mode flip is encoded in the stub's with.dry_run input, overridable per-ring, and require_confirmation: true holds the ring1→stable promotion for a human go/no-go.
Untracked prerequisites
- Repo-admin action (GitHub UI/API settings, not code): on ring-0
.github-privateenable 'Require approval for workflows from all outside contributors', and configure a per-repo PR cap for users without write access with a bypass list includingdependabot[bot]and org-leads (where GitHub supports it). Covered operationally by Phase 0. - Close the motivating spam PR
petry-projects/.github-private#1976by hand as part of Phase 0 (cross-repo; cannot be wired as a blocked_by edge).
Phase index (realigned)
- Phase 0 — [Phase 0] Layer 0 GitHub-native controls and close the motivating incident #1201 — Layer 0 native + close incident (hands-off; admin-UI work).
- Phase 1 — [Phase 1] Fix the description-quality check so an unfilled template is not read as complete #1202 —
scripts/lib/safety-checks.sh::sc_description_missing(vendored lib). PR feat: implement issue #1202 — [Phase 1] safety-checks lib with sc_description_missing #1218 in flight. - Phase 2 — [Phase 2] Deterministic spam-PR scoring script and config #1203 —
scripts/spam-pr-score.shdeterministic scorer (vendored script). - Phase 3 — [Phase 3] spam-pr-guard workflow in DRY_RUN, with the section 4 row and interaction contract #1204 — The reusable + stub + tests + registry entry + deploy wiring.
- Phase 4 — [Phase 4] Repo-local standard document for spam-pr-guard #1205 — Canonical
standards/spam-pr-guard.mdridingstandards/v1-stable. - Phase 5 — [Phase 5] DRY_RUN soak, threshold tuning without overfitting, and go/no-go to enable label/close #1206 — Canary ring progression
next → ring0 → ring1 → stablewithrequire_confirmationgo/no-go. - Phase 6 — [Phase 6] Stale backstop for needs-info and weekly reporting #1207 —
stale-managershort-window forneeds-info+ weekly reporting (vendored extensions).
Planned from idea discussion #1198 by the BMAD Scrum Master initiative-planner, realigned to the fleet vendored-reusable + caller-stub + canary-rings shape. Inert until a maintainer adds initiative:auto.
Activity
don-petry commentedon Oct 5, 2026
Initiative driver — stale in-flight slot(s) detected
The following open sub-issue(s) still carry the
dev-leadlabel but havehad no dev-lead activity for ≥ 72h, so they are occupying an in-flight
slot without progressing: #1202.
No labels were changed. A human should decide whether to split-and-close, retry,
or park each one so the slot is freed for the rest of the epic.
feat: implement issue #1202 — [Phase 1] safety-checks lib with sc_des…