feat(docs): define inactivity closure policies for issues and PRs (#452)

WilliamBerryiii · web-flow · commit 5e710fdb3896 · 2026-02-09T15:17:14.000-08:00
## Description Defines inactivity closure policies for issues, discussions, and pull requests to reduce noise from stale items. **Issue and discussion policy** (GOVERNANCE.md) — Issues inactive for 60 days receive a `stale` label and warning comment. If no activity follows within 14 days (74 days total), the issue is closed as `not_planned` with a `closed-stale` label. Exemptions: `pinned`, `security`, `do-not-close`, and milestone-assigned issues. Discussions follow the same thresholds with manual enforcement until tooling supports automation. **Pull request policy** (CONTRIBUTING.md) — Active PRs waiting on the author for 14 days receive a `stale` label. If no author activity follows within 7 days (21 days total), the PR is closed. Draft PRs are fully exempt. Additional exemptions: `do-not-close` and `waiting-on-reviewer` labels. ### Policy Summary | Scope | Stale After | Grace Period | Total | Exemptions | | :---- | :---------- | :----------- | :---- | :--------- | | Issues | 60 days | 14 days | 74 days | `pinned`, `security`, `do-not-close`, milestone-assigned | | Discussions | 60 days | 14 days | 74 days | Same as issues (manual enforcement) | | Active PRs | 14 days | 7 days | 21 days | draft, `do-not-close`, `waiting-on-reviewer` | Six supporting labels have been pre-created on the repository: `stale`, `closed-stale`, `do-not-close`, `pinned`, `waiting-on-author`, `waiting-on-reviewer`. ## Related Issue(s) - Closes #442 - Closes #443 ## Type of Change ### Code & Documentation - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [x] Documentation update - [ ] Breaking change (fix or feature that would cause existing functionality to change) ### Infrastructure - [ ] CI/CD pipeline changes - [ ] Build system changes - [ ] Configuration changes ### AI Artifacts - [ ] Copilot instructions (`.instructions.md`) - [ ] Copilot prompt (`.prompt.md`) - [ ] Copilot agent (`.agent.md`) - [ ] Skill package (`SKILL.md`) ### Other - [ ] Refactoring (no functional changes) - [ ] Performance improvement - [ ] Test changes only ## Testing - Verified cross-references between GOVERNANCE.md and CONTRIBUTING.md resolve correctly - Confirmed 6 GitHub labels exist on the repository - Markdown linting passes ## Checklist ### Required Checks - [x] I have read the [CONTRIBUTING](../CONTRIBUTING.md) document - [x] My changes follow the project coding standards - [x] I have updated documentation accordingly - [x] All new and existing linting checks pass ### Required Automated Checks - [x] Markdown linting: `npm run lint:md` - [x] Frontmatter validation: `npm run lint:frontmatter` ## Security Considerations - No secrets, tokens, or credentials introduced - No new dependencies added - No changes to CI/CD workflows or GitHub Actions - All changes are documentation only ## Additional Notes This PR is intentionally scoped to the governance and contributor documentation changes for inactivity policies. The community interaction message templates (Scenario 10 and 11 time-period values) are tracked separately alongside the backlog management pipeline in PR #448.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,7 +2,7 @@
 title: Contributing
 description: Guidelines for contributing code, documentation, and improvements to the HVE Core project
 author: HVE Core Team
-ms.date: 2025-11-05
+ms.date: 2026-02-07
 ms.topic: guide
 keywords:
   - contributing
@@ -60,6 +60,10 @@ We strongly recommend using the provided DevContainer, which comes pre-configure
   - [Suggesting Enhancements](#suggesting-enhancements)
   - [Your First Code Contribution](#your-first-code-contribution)
   - [Improving The Documentation](#improving-the-documentation)
+- [Pull Request Inactivity Policy](#pull-request-inactivity-policy)
+  - [Active Pull Requests](#active-pull-requests)
+  - [Draft Pull Requests](#draft-pull-requests)
+  - [Exemptions](#exemptions)
 - [Style Guides](#style-guides)
   - [Local Development Setup](#local-development-setup)
   - [Coding Conventions](#coding-conventions)
@@ -171,6 +175,45 @@ This project also includes a Dev Container for development work, and using that
 
 If you see issues with the documentation, please follow the [your first code contribution](#your-first-code-contribution) guidance.
 
+## Pull Request Inactivity Policy
+
+Pull requests that remain inactive accumulate merge conflicts and delay feedback loops. This section defines closure timelines for inactive PRs. Automation that enforces this policy is a separate effort that references these thresholds.
+
+For issue and discussion inactivity policy, see [Inactivity Closure Policy](./GOVERNANCE.md#inactivity-closure-policy) in GOVERNANCE.md.
+
+### Active Pull Requests
+
+The inactivity clock runs only when the PR is waiting on the author. Reviewer-side delays do not count against the author.
+
+| Stage  | Trigger                                                           | Label                 | Action                  |
+|:-------|:------------------------------------------------------------------|:----------------------|:------------------------|
+| Active | Author activity within the past 14 days while `waiting-on-author` | (none)                | Normal review cycle     |
+| Paused | PR is labeled `waiting-on-reviewer`                               | `waiting-on-reviewer` | Inactivity clock paused |
+| Stale  | 14 days without author activity while `waiting-on-author`         | `stale`               | Reminder comment posted |
+| Closed | 7 days after `stale` label without author activity                | `closed-stale`        | PR closed with summary  |
+
+Label usage:
+
+- `waiting-on-author` is applied when the reviewer requests changes or the author needs to resolve conflicts. The inactivity clock starts.
+- `waiting-on-reviewer` is applied when the author has addressed feedback and awaits re-review. The inactivity clock pauses.
+
+### Draft Pull Requests
+
+Draft PRs are fully exempt from inactivity closure. Converting a draft to "ready for review" starts the normal active PR lifecycle.
+
+### Exemptions
+
+The following conditions prevent automatic closure of a pull request:
+
+- PR is in draft state
+- PR is labeled `do-not-close`
+- PR is labeled `waiting-on-reviewer`
+
+Reopening rules:
+
+- Authors can reopen a stale-closed PR at any time with updated changes
+- Reopening removes the `stale` label and resets the inactivity clock
+
 ## Style Guides
 
 This project uses automated linters to ensure code quality and consistency. These linters can be run locally using the npm scripts described in the [Build and Validation Requirements](#build-and-validation-requirements) section.
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
@@ -2,7 +2,7 @@
 title: Governance
 description: Project governance model, roles, decision-making processes, and contribution authority for HVE Core
 author: HVE Core Team
-ms.date: 2026-01-21
+ms.date: 2026-02-07
 ms.topic: reference
 keywords:
   - governance
@@ -154,6 +154,36 @@ When contributors disagree on technical or process matters:
 
 Code of conduct violations follow the process defined in [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
 
+## Inactivity Closure Policy
+
+Open issues and discussions that remain inactive create noise for contributors and maintainers. This section defines the lifecycle policy for closing inactive items. Automation that enforces this policy (stale bot, scheduled workflows) is a separate effort that references these thresholds.
+
+For pull request inactivity policy, see [Pull Request Inactivity Policy](./CONTRIBUTING.md#pull-request-inactivity-policy) in CONTRIBUTING.md.
+
+### Issues
+
+Issue inactivity follows a three-stage lifecycle:
+
+| Stage        | Trigger                                      | Label          | Action                        |
+|:-------------|:---------------------------------------------|:---------------|:------------------------------|
+| Active       | Any activity within the past 60 days         | (none)         | Normal lifecycle              |
+| Stale        | 60 days without activity                     | `stale`        | Warning comment posted        |
+| Closed-stale | 14 days after `stale` label without activity | `closed-stale` | Issue closed as `not_planned` |
+
+Exemptions that prevent automatic closure:
+
+* Issues labeled `pinned`, `security`, or `do-not-close`
+* Issues assigned to any milestone
+
+Reopening rules:
+
+* Any participant can reopen a stale-closed issue with additional context
+* Reopening removes the `stale` label and resets the inactivity clock
+
+### Discussions
+
+The same 60-day warning and 14-day closure thresholds apply to GitHub Discussions in principle. The same exemptions that prevent automatic closure for issues (pinned, security, do-not-close, or assigned to a milestone) and the same reopening behavior (reopening clears any stale status and resets the inactivity clock) apply to Discussions. Because current automation tooling (actions/stale) does not support Discussions, enforcement is manual through periodic triage until dedicated tooling is implemented.
+
 ## Access Continuity
 
 Project continuity is ensured through Microsoft stewardship:
