From aa2ea7b5a159af9f7c2f423c0c3a215e4fc27c3e Mon Sep 17 00:00:00 2001 From: Alexander Payne Date: Wed, 29 Apr 2026 21:20:40 -0400 Subject: [PATCH] docs: add 7-day stale-conflict PR policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Issue #491 requires a documented 7-day stale-conflict policy. This commit adds docs/STALE_PR_POLICY.md specifying: - 7-day threshold for merge-conflicted PRs - Standard closure procedure with rationale comment - Exceptions for active milestones, explicit requests, experimental work - Daily check → pester → close workflow Closes #491 --- docs/STALE_PR_POLICY.md | 45 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/STALE_PR_POLICY.md diff --git a/docs/STALE_PR_POLICY.md b/docs/STALE_PR_POLICY.md new file mode 100644 index 0000000..5cc3014 --- /dev/null +++ b/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. -- 2.43.0