chore: reactivate stale issue cleanup

.github/workflows/stale.yml

@@ -13,7 +13,8 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v10
+      # Pinned from actions/stale@v10; update deliberately when refreshing the policy.
+      - uses: actions/stale@eb5cf3af3ac0a1aa4c9c45633dd1ae542a27a899
         with:
           days-before-stale: 14
           days-before-close: 7
@@ -28,7 +29,7 @@ jobs:
             you can share the requested information.
           stale-issue-label: 'stale'
           only-labels: 'needs-info'
-          exempt-issue-labels: 'pinned,keep-open,bug,security'
+          exempt-issue-labels: 'pinned,keep-open,release-blocker,security'
           # Don't touch PRs — `actions/stale` defaults can be aggressive
           # there. We only want it for `needs-info` issues.
           days-before-pr-stale: -1

docs/ISSUE_TRIAGE.md

@@ -0,0 +1,69 @@
+# Issue Triage
+
+## Stale `needs-info` cleanup
+
+The stale workflow only acts on issues that a maintainer has explicitly labeled
+`needs-info`. This keeps old roadmap, release, security, and current milestone
+work out of automatic cleanup unless a maintainer first marks the issue as
+waiting on reporter input.
+
+Required labels:
+
+- `needs-info`: waiting on reporter information or current-version reproduction details.
+- `stale`: inactive `needs-info` issue pending automatic closure.
+- `keep-open`: protected because maintainers intentionally keep it open.
+- `pinned`: protected maintainer issue.
+
+Protected labels for stale cleanup:
+
+- `pinned`
+- `keep-open`
+- `release-blocker`
+- `security`
+
+A `bug` issue is not protected just because it is a bug. If a maintainer has
+also labeled it `needs-info`, it is eligible for stale warning and closure
+unless one of the protected labels above is present.
+
+## Dry-run queries
+
+Run these before changing stale policy or doing a manual cleanup pass:
+
+```sh
+STALE_CUTOFF=$(python3 -c 'from datetime import date, timedelta; print(date.today() - timedelta(days=45))')
+NEEDS_INFO_CUTOFF=$(python3 -c 'from datetime import date, timedelta; print(date.today() - timedelta(days=30))')
+
+gh issue list --repo Hmbown/CodeWhale --state open \
+  --search "updated:<${STALE_CUTOFF}" \
+  --limit 100 \
+  --json number,title,updatedAt,labels,url
+
+gh issue list --repo Hmbown/CodeWhale --state open \
+  --search "label:needs-info updated:<${NEEDS_INFO_CUTOFF}" \
+  --limit 100 \
+  --json number,title,updatedAt,labels,url
+
+gh issue list --repo Hmbown/CodeWhale --state open \
+  --search "created:<${STALE_CUTOFF} comments:0 -label:keep-open -label:release-blocker -label:security" \
+  --limit 100 \
+  --json number,title,createdAt,updatedAt,labels,url
+```
+
+Use `updatedAt`, labels, and current release relevance as the closure basis.
+Creation date alone is too aggressive.
+
+## First cleanup pass
+
+Before relying on automation, perform one manual pass:
+
+- Label unresolved old bug reports as `needs-info` only after asking for
+  current-version reproduction details.
+- Close obvious GUI, VS Code, and web UI duplicates with links to canonical
+  desktop/runtime issues.
+- Close old brand-discussion issues as superseded when the CodeWhale rebrand
+  and README/history work already covers them.
+- Protect intentional v0.9.0 roadmap shards with `keep-open` or close them as
+  superseded by a canonical epic.
+
+Do not close release blockers, security issues, or active milestone work from
+stale automation alone.