msd-core/docs/agents/triage-labels.md

Triage Labels

Maps the five canonical triage roles to the actual label strings in open-gsd/gsd-core.

Canonical role	Label in this repo	Notes
needs-triage	needs-triage	Auto-applied by GitHub Action on every new issue
needs-info	needs-reproduction	Waiting on reporter — cannot reproduce, more info required
ready-for-agent	confirmed-bug	Bug verified + fully specified — AFK agent can pick up. This is the fix gate (RULESET.CONTRIB.CLASSIFY.fix); bug-remediation workflows scope on it.
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

• confirmed-bug is the AFK-agent-ready signal for bugs. It means "verified reproducible bug" and is the gate the fix workflow requires before any code is written. Apply it (in addition to bug) when triage reproduces/verifies a bug. The legacy confirmed label ("bug verified to exist") is retained only for back-compat in the duplicate-sweep exempt list — use confirmed-bug for new triage.
• For enhancements and features, maintainer approval is approved-enhancement / approved-feature respectively. A contributor (human or agent) may not write code until one of these is applied.
• There is no separate "ready-for-human" vs "ready-for-agent" distinction for enhancements — both flow through the same approved-* labels. If the work requires human judgment (design decisions, external access), note it in the issue body.
• needs-triage is removed when any other state label is applied.
• needs-reproduction is used instead of the generic needs-info — be specific in triage comments about what reproduction steps or information are missing.

Duplicate detection lifecycle

The possible-duplicate label is managed by three GitHub Actions workflows that together form a self-service deduplication loop:

1. Detect on open — When an issue is opened, duplicate-check.yml scores its title against all other open issues using Dice-coefficient similarity. If any match clears the threshold, the bot posts a challenge comment listing the similar issues and applies possible-duplicate.
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.