docs/STALE_PR_POLICY.md

@@ -0,0 +1,45 @@
+# Stale/Blocked PR Policy
+
+**Scope:** `hermes-agent` and all Timmy_Foundation repositories  
+**Effective:** 2026-04-29  
+**Related:** Issue timmy-home#491, hermes-agent#129/#108/#107
+
+## Purpose
+
+Blocked or merge-conflicted PRs stall delivery and clutter the pipeline. This
+policy defines when such PRs must be closed and how exceptions are handled.
+
+## 7-Day Stale-Conflict Rule
+
+- A PR that **cannot be merged due to merge conflicts** and remains in that
+  state for **7 consecutive days** is considered _stale-blocked_.
+- Stale-blocked PRs should be **closed** with a comment explaining:
+  1. why the PR is being closed (merge conflicts, unrebased)
+  2. whether the underlying work is still needed
+  3. how to rebase or reopen if still relevant
+- The closure comment should reference the related issue(s) or epic.
+
+## Exceptions
+
+A PR may be exempt from automatic closure if:
+- It is linked to an active milestone with an explicit rebase plan
+- The author has explicitly requested extra time in a comment
+- The PR is kept open intentionally for long-running experimental work
+  (must carry the `experimental` label)
+
+## Process
+
+1. **Daily check** (via cron): scan all open PRs with `mergeable = false`
+2. **Age filter**: if PR is >7 days old and `blocked = true` or conflicts present → flag
+3. **Comment**: pester author to rebase within 48h
+4. **Close**: if no action after 48h, close with standard closure message
+
+## Record
+
+Closed PRs are documented in:
+- timmy-home: the cross-audit triage report links to closed PRs
+- hermes-agent: closure comments explain the decision in each case
+
+---
+
+This policy directly implements timmy-home#491's final acceptance criterion.