docs: update CONTRIBUTING.md for spam protection (#800) #935

Gap

PR #800 adds spam protection and auto-lock CI workflows. Contributors need to know about guardrails that automatically moderate and lock content.

Spam Protection Mechanics (from PR #800)

What is Detected

The squad-comment-moderation workflow runs three jobs:

1. Comment Moderation — On every new or edited issue comment:

   • Blocks malicious links (shortened URLs via bit.ly, tinyurl, t.co, goo.gl, rb.gy)
   • Blocks file-sharing services (dropbox.com, drive.google, mega.nz, mediafire)
   • Blocks crypto scam patterns ("free bitcoin", "guaranteed profit", etc.)
   • Blocks mass-mentions (4+ @-mentions flagged)
   • Contributors are exempt from these checks

2. Spam Scoring — On newly opened issues:

   • Script: scripts/moderate-spam.mjs
   • Calculates spam score based on content signals and author profile
   • Score ≥ 5: Issue is closed and labeled spam, spam comment posted
   • Score 3-4: Issue labeled suspicious, but remains open (for maintainer review)
   • Issue comments include detected signals (e.g., "content-pattern: shortUrls, mass-mentions: 6")

3. Auto-Lock Stale — Daily cron job (scripts/lock-stale.mjs):

   • Locks closed issues and PRs with no activity for 30+ days
   • Prevents "necro-spam" (spam replies on old closed issues)

Scoring Thresholds

• Content patterns (shortURLs, fileSharing, cryptoScam, adultContent): +3 points each
• Mass-mentions (4+ @-mentions): +1 point
• New account profile (< 30 days old, 0 repos, 0 followers): +2 points
• Action thresholds:
  • Score ≥ 5: Auto-close as spam
  • Score 3-4: Label as suspicious (maintainer review required)

What Triggers Detection

• Shortened URLs in comments/issues
• File-sharing service links
• Crypto/investment scam language
• Adult content patterns
• Mass @-mentions (4 or more in one comment)
• New accounts with suspicious profiles + sketchy content

Doc Location Strategy

File to Update: CONTRIBUTING.md (exists at repo root)

New Section: Add a subsection under a "Community Guidelines" or "Contributing Code & Discussions" section (after prerequisites and setup steps, before git workflow):

## Community Guidelines & Spam Protection

Our repository is protected by automated spam detection to maintain a safe, productive community. Here's what you need to know:

### Spam Detection Rules
- **Automated comment moderation** filters malicious links (shortened URLs, file-sharing services) and mass-mentions from all comments
- **Issue spam scoring** evaluates newly opened issues for spam signals and auto-closes suspected spam with explanations
- **Auto-lock stale** locks issues and PRs inactive for 30+ days to prevent spam replies on old content

### What Gets Flagged
- Shortened URLs (bit.ly, tinyurl, t.co, goo.gl, rb.gy)
- File-sharing links (Dropbox, Google Drive, Mega, MediaFire)
- Crypto/investment scams ("free bitcoin", "guaranteed profit", etc.)
- Adult content patterns
- Mass-mentions (4+ @-mentions in one comment)
- New accounts (< 30 days old) with 0 repos, 0 followers + suspicious content

### What Happens If You're Flagged
- **Comment blocked** — moderation action filters your comment before it's posted (contributors are exempt)
- **Issue closed as spam** (score ≥ 5) — auto-closed with explanation; contact maintainers to reopen if it was a mistake
- **Issue labeled "suspicious"** (score 3-4) — remains open but flagged for maintainer review
- **Issue locked** — if inactive for 30+ days, locked to prevent spam replies

### If You're Mistaken for Spam
If your legitimate issue/comment is caught by spam detection, please contact a maintainer to review and reopen. We're sorry for the false positive and will help you get back on track.

### For Maintainers
Spam issues are labeled `spam` and closed with a comment explaining detected signals. Review the comment for details. If legitimate, reopen and adjust if needed.

Audience: Both contributors (what they should expect) and maintainers (how to handle false positives)

Acceptance Criteria

• CONTRIBUTING.md updated with new "Community Guidelines & Spam Protection" section
• Section includes all 5 categories of detection (shortened URLs, file-sharing, crypto, adult, mass-mentions, new account profile)
• Auto-lock behavior explained (30+ day inactivity threshold)
• Scoring thresholds documented (≥5 = auto-close, 3-4 = suspicious label)
• Guidance for contributors whose content was caught (contact maintainers)
• PR feat(ci): add comment spam protection and auto-lock stale issues (#751) [ON HOLD] #800 is merged

Depends on: PR #800 merge

Source: docs-opportunity-scanner (2026-04-08)