docs(agents): align triage state labels - #2809
Closed
elezar wants to merge 1 commit into
Closed
Conversation
elezar
requested review from
derekwaynecarr,
mrunalp and
sjenning
as code owners
August 19, 2026 14:47
6 tasks
Signed-off-by: Evan Lezar <elezar@nvidia.com>
elezar
force-pushed
the
codex/update-triage-state-labels
branch
from
August 24, 2026 14:49
46785d7 to
d11f351
Compare
|
This pull request has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. |
github-actions
Bot
added
the
state:stale
Member
Author
|
As per offline discussion. Let's close this and reopen or create a follow-up. |
purp
added a commit
to purp/OpenShell
that referenced
this pull request
Sep 9, 2026
PR NVIDIA#2524 replaced the `state:*` lifecycle vocabulary with an `agent:*` namespace whose labels were never created on GitHub. `gh label list` returns nine `state:*` labels and zero `agent:*` labels, so every gate referring to the `agent:*` names was unreachable. This had a live functional consequence beyond documentation drift. `.github/workflows/stale.yml` exempted five phantom labels and omitted the four real in-flight states. As of 2026-09-09, 18 open issues carry `state:stale` while sitting in a state the workflow intends to exempt, including issues with open PRs and issues mid-implementation. That count was 17 on 2026-09-02, so the exposure is still growing. Restore the real vocabulary across the skills, contributor docs, and the stale workflow, and add `.agents/issue-lifecycle.yaml` as the canonical machine-readable source of truth. `agent:plan-requested` has no `state:*` predecessor; queue-mode planning is authorized by `state:accepted` or roadmap placement, which is what that label already means. The file records the phantom names under `never_existed` so future readers recognize stale references instead of treating them as valid gates. Document staleness as an orthogonal boundary rather than a lifecycle state, complete the CONTRIBUTING.md state table from four states to eight, and add a two-way drift check to `sync-agent-infra` so documentation and GitHub cannot diverge again unnoticed. PR NVIDIA#2809 fixed `.agents/skills/triage-issue/SKILL.md` alone and was closed unmerged on 2026-09-08. This change absorbs that file so the reconciliation stays complete. Refs: NVIDIA#2524, NVIDIA#2809, NVIDIA#454 Signed-off-by: Jim Meyer <jimeyer@nvidia.com>
purp
added a commit
to purp/OpenShell
that referenced
this pull request
Sep 9, 2026
The issue lifecycle was documented only in CONTRIBUTING.md, where it had grown to roughly 150 lines in the middle of a file that also covers build prerequisites, Rust cache setup, and CI. Contributors and agents who need the lifecycle have to read past unrelated material to find it, and there is no published page to link from an issue comment. Add a Contributing section to the published docs and move the lifecycle reference there as `docs/contributing/issue-lifecycle.mdx`. The page adds two diagrams that the prose could not express: the full state machine including the delegated states and the `state:needs-info` self-loop, and staleness as a boundary orthogonal to the lifecycle rather than a state within it. Reduce the CONTRIBUTING.md section to a pointer plus the two rules that come up day to day, and point `sync-agent-infra` at the published page so the drift check follows the content. CONTRIBUTING.md drops from 517 to 371 lines. `mise run docs` reports 0 errors, matching the pre-change baseline. Refs: NVIDIA#2524, NVIDIA#2809 Signed-off-by: Jim Meyer <jim@geekdaily.org>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Align the triage skill with the repository’s state-label workflow and clarify who may change each label.
Related Issue
No issue required: localized agent-workflow documentation correction.
Changes
state:acceptedandstate:agent-readyhuman-only.Testing
mise run markdown:lintpasses in~/.dotfiles/devenvs/openshell.mise run pre-commitpasses (blocked becausecargois unavailable in that devenv session).Checklist