docs(triage): parked issues stay open under the parked label; closing means fixed, duplicate or won't fix (GSTA-99)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [Unreleased]
+
+**An issue we intend to fix later now stays open under the `parked` label instead of being closed into a TODOS theme.** The Oct 11 triage closed 75 feature requests with a "not rejected, tracked in TODOS.md" note, and GitHub showed them as closed with no fix. Those 75 are reopened under `parked`, each with one comment saying where it is tracked and what fixes it, and the rule is written down: closing means fixed, duplicate or won't fix, each with its reason.
+
+### Added
+- **`docs/triage.md`**: the three issue states (open, parked, closed), how to park an issue (the label plus one comment naming where it is tracked and what fixes it), the three close reasons with their GitHub close reason and label, and where the Wave 9 themes live.
+- The `parked` label on garrytan/gstack: "Not fixed yet, not rejected: stays open; a comment says where it is tracked and what fixes it".
+
+### Changed
+- **`CONTRIBUTING.md`**: an "Issue triage" section ahead of the PR wave process, pointing at docs/triage.md.
+- **`TODOS.md`**: the Wave 9 feature-themes note says issues stay open under `parked` with a link to their theme, instead of closing with one.
+
 ## [1.91.221.0] - 2026-10-25
 
 **The session-start updater no longer skips because of its own session's workflow lease, and the autostash tests stop failing their first pass in Free Tests.** Since #3385, `gstack-session-update` skips the fast-forward while another session holds a workflow lease, and it means to ignore the session that started it (`--exclude-ancestry-of`). The check runs in the forked background updater, though, and passed the hook's own `$$`, which has exited by then, so the ancestry walk excluded nothing. A Claude Code process that had already run a skill (and so held a lease) and then started a session again in the same process (`/clear`, resume or compaction) logged `SKIP leased pid=<its own pid>` and never updated. `test/session-update-autostash.test.ts` hit the same gap plus a fixture leak: its first two fixtures spawned the updater with the whole parent environment, so it read the test preload's `GSTACK_LEASE_DIR`, which every test file in the same Bun process shares. A lease another file left there gave "Received: SKIP leased pid=3196/1m" where UPDATING or PULL_FAILED was expected, in 13 Free Tests runs since #3385 merged (each passed on the serial retry).

CONTRIBUTING.md

@@ -907,6 +907,14 @@ bun install && bun run build && ./setup
 
 This affects all projects. To revert: `git checkout main && git pull && bun run build && ./setup`.
 
+## Issue triage
+
+An issue is open, parked or closed, and closed means fixed, duplicate or won't
+fix, each with its reason in the closing comment. An issue we intend to fix
+later stays open under the `parked` label with one comment saying where it is
+tracked (a TODOS.md theme or a tracking issue) and what fixes it. The full rule,
+including the labels and the close reasons, is in [docs/triage.md](docs/triage.md).
+
 ## Community PR triage (wave process)
 
 When community PRs accumulate, batch them into themed waves:

TODOS.md

@@ -60,7 +60,7 @@ Each item was decided in the Wave 9 plan and parked with its reason. Credit the
 
 ### P3: feature themes from the Wave 9 triage (filed 2026-10-11)
 
-The 73 open feature requests, grouped by theme with counted demand (issues in the theme). Each issue closes with a link to its theme here; the three largest cross-cutting themes (new hosts, provider pluralism, install footprint) stay open as tracking issues. Pick a theme up as a whole and credit every linked reporter.
+The 73 open feature requests, grouped by theme with counted demand (issues in the theme). Each issue stays open under the `parked` label with a link to its theme here (the rule is in docs/triage.md); the three largest cross-cutting themes (new hosts, provider pluralism, install footprint) also have tracking issues. Pick a theme up as a whole and credit every linked reporter.
 
 - **New hosts (8 issues, plus #3061 above and 9 PRs parked on Oct 8)** — Kimi CLI (#1072), Gemini CLI (#1247), Pi Agent (#1288), Claude Desktop Cowork (#1345), Letta Code (#2117), team mode for non-Claude hosts (#890), `/retro global` discovery of Antigravity (#1977) and Kimi Code / OMP sessions (#2917). Waits for the host-config work; see "Parked contributor ideas (Oct 8 triage)" for the parked host PRs. **Priority:** P3.
 - **Provider pluralism (7 issues, plus #3122)** — Gemini CLI as an outside-voice backend (#619), non-OpenAI image providers in `design` (#990), Codex-native `image_gen` in the `design` binary's own generate, evolve and prototype calls (#2174; design-shotgun itself already uses `$imagegen` on Codex since #2175), GPT-6 Sol/Luna tiers in Codex call routing (#2943), a `/grok` review port (#2947), Codex review token usage (#2948), Codex refresh-token recovery docs (#1542), and a configurable PR review bot instead of hard-coded Greptile in /review, /ship and /retro (#3122, folded here by decision D4). One provider seam serves all of them. **Priority:** P3.

docs/triage.md

@@ -0,0 +1,76 @@
+# Issue triage
+
+How gstack issues move between open, parked and closed, and what each state
+promises the reporter. The rule exists because a closed issue reads as "fixed"
+or "rejected" to the person who filed it. On 2026-10-11 a triage pass closed 75
+feature requests into TODOS.md themes with a "not rejected" note, and reporters
+still saw a closed issue with no fix. Those were reopened on 2026-10-25 under
+the `parked` label, and this page is the rule going forward.
+
+## The three states
+
+| State | Meaning | How it looks on GitHub |
+|-------|---------|------------------------|
+| **Open** | We intend to act on it and nothing is decided yet, or a lane is on it now. | Open, no `parked` label. `next-wave` marks issues accepted for the next fix wave. |
+| **Parked** | We intend to fix it later, not now. | Open, labelled `parked`, with one comment that says where it is tracked and what fixes it. |
+| **Closed** | Fixed, duplicate, or won't fix. Nothing else. | Closed with the matching reason (below). |
+
+An issue we still intend to fix is never closed. Grouping it into a theme,
+folding it into a tracking issue, or deciding it waits for other work are all
+"parked", not "closed".
+
+## Parking an issue
+
+1. Add the `parked` label.
+2. Post one comment with two facts: **where it is tracked** (the TODOS.md
+   theme, by link, or the tracking issue such as #3137, #3138 or #3139) and
+   **what fixes it** (the work that, when it ships, closes this issue). One or
+   two sentences. No other comment is needed.
+3. Add the issue number to the TODOS.md entry so the theme credits the reporter
+   when it is picked up.
+
+When the work ships, close the issue as fixed with the version or PR, and the
+label goes with it. When a lane picks a parked issue up, it may remove the
+label while it works on it; an issue the lane later drops goes back to parked
+with an updated comment.
+
+## Closing an issue
+
+Each close names its reason in the closing comment. GitHub's close reason and
+the labels match:
+
+| Reason | Comment says | Close reason | Label |
+|--------|--------------|--------------|-------|
+| **Fixed** | the version, commit or PR that fixed it, and what changed | completed | — |
+| **Duplicate** | the issue that tracks it (and that issue is open or parked, not closed) | not planned | `duplicate` |
+| **Won't fix** | why: out of scope, a different design was chosen, the premise no longer holds | not planned | `wontfix` |
+
+A duplicate of a parked issue is still a duplicate: close it with the link,
+and the parked issue's comment or TODOS.md entry credits both reporters. A
+report that does not reproduce on current main closes as won't fix with the
+version it was checked against and an invitation to reopen with a repro.
+
+## Labels this page uses
+
+- `parked`: not fixed yet, not rejected; stays open, with a comment saying
+  where it is tracked and what fixes it.
+- `tracking`: a tracking issue for a theme; stays open until the theme ships.
+- `next-wave`: accepted for the next fix wave.
+- `duplicate`, `wontfix`: the two non-fix close reasons.
+- `needs Windows verification`: a merged fix awaiting confirmation on real
+  Windows hardware; the issue stays open until then.
+
+## Where the themes live
+
+Parked feature requests are grouped in TODOS.md under "feature themes from the
+Wave 9 triage": new hosts (#3137), provider pluralism (#3138), install
+footprint and layout (#3139), new skills, ship/review/safety, planning reviews,
+state root and project identity, browser and mobile QA, prompt cost and skill
+shape, customization and localization, retro, and CI supply chain. Parked bugs
+sit under "parked in Wave 9" in the same file. Pick a theme up as a whole and
+credit every linked reporter in the CHANGELOG entry.
+
+Community pull requests follow the wave process in
+[CONTRIBUTING.md](../CONTRIBUTING.md#community-pr-triage-wave-process); a
+closed PR gets the same courtesy as a closed issue: a comment saying why and
+what supersedes it.