feat(#1180): hard-gate the GSD Version requirement on bug reports (#1181)

Auto-close bug reports opened without a valid GSD Version (Issue Forms enforce required only in the web UI). Bug reports only; version-shaped validation; version-exempt opt-out. Closes #1180

docs/agents/triage-labels.md

@@ -10,6 +10,8 @@ Maps the five canonical triage roles to the actual label strings in `open-gsd/gs
 | `ready-for-human` | `approved-enhancement` / `approved-feature` | Enhancement/feature approved by maintainer — human codes it |
 | `wontfix`         | `wontfix`                | Will not be actioned                                           |
 | `possible-duplicate` | `possible-duplicate` | Applied by the Duplicate check workflow when a new issue's title closely matches existing open issues. The reporter (or a maintainer) replies justifying why it is not a duplicate within 24h, or the Duplicate auto-close sweep closes it. A reply clears this label and applies needs-maintainer-review for human adjudication. React 👎 to the bot comment to veto auto-close. |
+| `needs-version` | `needs-version` | Applied by the Version gate workflow when a bug report is auto-closed for missing a valid GSD Version. Edit the issue to add the version and reopen it. |
+| `version-exempt` | `version-exempt` | Maintainer-only opt-out label. Prevents the Version gate from closing an issue where a version genuinely does not apply. |
 
 ## Notes on this repo's label model
 
@@ -27,3 +29,14 @@ The `possible-duplicate` label is managed by three GitHub Actions workflows that
 2. **Challenge comment + reporter window** — The reporter (or a maintainer) has `DEFAULT_WINDOW_HOURS` (24h) to reply explaining why the issue is not a duplicate. Reacting 👎 to the bot comment also signals the reporter objects to auto-close.
 3. **Daily sweep auto-close** — `duplicate-sweep.yml` runs at 07:00 UTC daily. For each open issue with `possible-duplicate`, it checks whether the window has elapsed, whether the reporter replied, and whether a 👎 reaction exists. Issues with exempt labels (`priority: critical`, `pinned`, `confirmed-bug`, `confirmed`, `fix-pending`) are never auto-closed. Issues that pass the close check receive a closing comment and are closed with `state_reason: duplicate`.
 4. **Reporter reply clears label** — `remove-duplicate-label.yml` fires on every new non-bot comment. If the issue still carries `possible-duplicate`, it removes that label and applies `needs-maintainer-review` (the value of `HUMAN_REVIEW_LABEL` in `scripts/issue-dedupe.cjs`), routing the issue to a maintainer for manual adjudication.
+
+## Version gate lifecycle
+
+The `needs-version` label is managed by a single GitHub Actions workflow that runs immediately on issue open:
+
+1. **Gate on open** — When an issue is opened, `version-gate.yml` checks whether it is a bug report (has the `bug` label, or its body contains a `### GSD Version` heading from the bug template). Non-bug issues are skipped.
+2. **Version check** — The gate extracts the value under the `### GSD Version` heading. A value is considered valid if it contains a semver-ish token (e.g. `1.18.0`, `v1.4.1`, `1.18.0-dev`) or a git commit SHA (7-40 hex chars). Missing, blank, `_No response_`, or junk values like `idk` are treated as absent.
+3. **Auto-close** — If the version is absent or invalid, the workflow posts a comment with instructions and closes the issue as `not_planned`, then applies `needs-version`.
+4. **Reopen path** — The reporter edits the issue to add a valid version and reopens it. Alternatively, a maintainer can add the `version-exempt` label to any bug where a version does not apply (e.g. docs bugs, spec questions), which prevents the gate from closing it on future edits.
+
+The gate logic lives in `scripts/issue-version-gate.cjs` (pure exports, no GitHub API dependency) and is covered by `tests/issue-version-gate.test.cjs`.