docs: add contributor protection policy for AI agents (#3151)

Prevents agents from silently overwriting external contributor PRs.
Prompted by PR #3143 where bgjackma's work was reimplemented without
attribution.

- CONTRIBUTING.md: "Your PR Will Not Be Overwritten" section
- AGENT_INSTRUCTIONS.md: check-before-you-build procedure + CONTRIBUTING.md reference
- AGENTS.md: cross-reference to contributor protection

Author: maphew

AGENTS.md

@@ -9,6 +9,7 @@ This file exists for compatibility with tools that look for AGENTS.md.
 - **Issue Tracking** - How to use bd for work management
 - **Development Guidelines** - Code standards and testing
 - **Visual Design System** - Status icons, colors, and semantic styling for CLI output
+- **Contributor Protection** - Read [CONTRIBUTING.md](CONTRIBUTING.md) before handling external PRs
 
 ## Visual Design Anti-Patterns
 

AGENT_INSTRUCTIONS.md

@@ -111,6 +111,25 @@ Crew workers push directly to main. **Never create pull requests.**
 - When handling external PRs, use fix-merge: checkout the PR branch locally,
   fix/rebase onto main, merge locally, `git push`, then close the PR
 
+### External Contributor PRs: Check Before You Build
+
+**Read [CONTRIBUTING.md](CONTRIBUTING.md)** — it contains promises we've made to contributors. Violating them damages trust and community.
+
+**Before implementing any feature or fix, check for existing open PRs on the same topic:**
+
+```bash
+gh pr list --repo gastownhall/beads --state open --search "<topic keywords>" --json number,title,author,headRefName
+```
+
+**Contributor work gets priority.** If an external PR already exists:
+1. **Review it first** — read the diff, understand the approach
+2. **Build on their work, don't rewrite it** — checkout their branch, fix/adapt as needed
+3. **Preserve their tests** — contributor tests are signal; keep them unless they're wrong
+4. **Attribute properly** — use `Co-authored-by:` in commits, reference their PR number
+5. **Never auto-close a contributor PR** by merging a rewrite — that discards their contribution silently
+
+If you must rewrite (e.g., fundamentally different approach needed), explain why on the original PR and credit the contributor's design/tests in your commits.
+
 This is enforced by pre-use hooks. If you try `gh pr create`, it will be blocked.
 
 ## Landing the Plane

CONTRIBUTING.md

@@ -277,6 +277,17 @@ When proposing new features:
 - Consider backwards compatibility
 - Discuss alternatives you've considered
 
+## Your PR Will Not Be Overwritten
+
+This project uses AI agents for maintenance. We've established strict rules to protect contributor work:
+
+- **Your PR has priority.** If you've submitted a PR, agents must review and build on your work — not rewrite it from scratch.
+- **Your tests matter.** Agents must preserve contributor tests unless they're actually wrong.
+- **You'll get attribution.** Your commits and `Co-authored-by:` will be preserved.
+- **No silent closes.** Your PR will never be auto-closed by a parallel rewrite. If changes are needed, they'll be discussed on your PR.
+
+If any of this goes wrong, please open an issue — we take contributor experience seriously.
+
 ## Code Review Process
 
 All contributions go through code review: