Require issue type and workflow status labels #513

New Issue

2026-07-08T03:05:23-05:00

jcwalker3 commented

2026-07-08 03:05:23 -05:00

Problem

Issues are difficult to scan because their process state is mostly buried inside comments. A controller, author, reviewer, merger, reconciler, or human must open individual issues to know whether they are discussion-only, ready for work, claimed, blocked, in progress, have a PR open, are awaiting review, or need reconciliation.

Discussion issues are especially easy to confuse with implementation issues unless they are clearly labeled.

Required behavior

Every issue must have labels that identify:

What kind of issue it is.
Where it is in the workflow process.

At minimum, every issue should have:

one type:* label
one status:* label

Discussion issues must be labeled:

type:discussion

Required issue type labels

Create or standardize these labels:

type:bug
type:feature
type:process
type:workflow
type:guardrail
type:docs
type:test
type:discussion
type:umbrella
type:cleanup

Required workflow status labels

Create or standardize these labels:

status:triage
status:ready
status:claimed
status:in-progress
status:blocked
status:needs-review
status:pr-open
status:approved
status:merged
status:reconcile
status:done
status:duplicate
status:wontfix

Status label rules

Only one status:* label should be active on an issue at a time.

When the issue moves forward, the old status:* label must be removed and the new one applied.

Suggested lifecycle:

New issue created:
- status:triage or status:ready
Issue selected by an author:
- status:claimed
Author starts work:
- status:in-progress
Work is blocked:
- status:blocked
PR opened:
- status:pr-open
PR approved:
- status:approved
PR merged but issue still needs closure/reconciliation:
- status:reconcile
Issue fully complete:
- status:done
Duplicate issue:
- status:duplicate
Discussion-only issue:

type:discussion
usually status:triage, status:ready, or status:done depending on whether a conclusion/action has been reached

Discussion issue rules

Discussion issues must be labeled type:discussion.

A discussion issue should not be treated as implementation-ready unless it also has a clear implementation status and next action.

If a discussion produces implementation work, either:

convert the discussion issue into an implementation issue by changing labels and adding acceptance criteria, or
create child implementation issues and leave the discussion issue as type:discussion.

MCP/tooling requirements

Add tooling or validation so that issue creation and workflow transitions enforce labels.

Required behavior:

Creating an issue should require or recommend a type:* label.
Creating an issue should require or recommend an initial status:* label.
Discussion issues must receive type:discussion.
Moving an issue to in-progress should replace the old status:* label with status:in-progress.
Opening a PR that closes an issue should move the issue to status:pr-open.
Approved PRs should move linked issues to status:approved if appropriate.
Merged PRs should move linked issues to status:reconcile or status:done depending on the workflow.
Duplicate closures should apply status:duplicate.

Acceptance criteria

Define the canonical type:* and status:* label taxonomy in documentation.
Add or update templates so new issues include correct labels.
Add workflow validation to detect issues missing:
- a type:* label
- a status:* label
Add validation that discussion issues are labeled type:discussion.
Add validation that more than one status:* label is not active unless explicitly allowed.
Add tool/helper behavior to transition status labels during:
- claim
- start work
- block
- PR open
- approval
- merge
- reconciliation
- duplicate closure
Add tests covering:
- valid labeled issue
- issue missing type:*
- issue missing status:*
- discussion issue missing type:discussion
- multiple conflicting status:* labels
- status transition removes old status label
- PR-open transition applies status:pr-open
- duplicate transition applies status:duplicate
Ensure existing issue, PR, reviewer, merger, and reconciler workflows still pass.

Out of scope

Replacing thread comments.
Replacing [CONTROLLER HANDOFF] or [THREAD STATE LEDGER].
Weakening role permissions.
Automatically closing issues without controller/reconciler rules.

Desired outcome

The issue queue should be readable at a glance.

A human or LLM should be able to scan labels and immediately know:

what kind of issue it is
whether it is discussion-only or implementation-ready
where it is in the workflow
what class of actor should touch it next

## Problem Issues are difficult to scan because their process state is mostly buried inside comments. A controller, author, reviewer, merger, reconciler, or human must open individual issues to know whether they are discussion-only, ready for work, claimed, blocked, in progress, have a PR open, are awaiting review, or need reconciliation. Discussion issues are especially easy to confuse with implementation issues unless they are clearly labeled. ## Required behavior Every issue must have labels that identify: 1. What kind of issue it is. 2. Where it is in the workflow process. At minimum, every issue should have: - one `type:*` label - one `status:*` label Discussion issues must be labeled: - `type:discussion` ## Required issue type labels Create or standardize these labels: - `type:bug` - `type:feature` - `type:process` - `type:workflow` - `type:guardrail` - `type:docs` - `type:test` - `type:discussion` - `type:umbrella` - `type:cleanup` ## Required workflow status labels Create or standardize these labels: - `status:triage` - `status:ready` - `status:claimed` - `status:in-progress` - `status:blocked` - `status:needs-review` - `status:pr-open` - `status:approved` - `status:merged` - `status:reconcile` - `status:done` - `status:duplicate` - `status:wontfix` ## Status label rules Only one `status:*` label should be active on an issue at a time. When the issue moves forward, the old `status:*` label must be removed and the new one applied. Suggested lifecycle: 1. New issue created: - `status:triage` or `status:ready` 2. Issue selected by an author: - `status:claimed` 3. Author starts work: - `status:in-progress` 4. Work is blocked: - `status:blocked` 5. PR opened: - `status:pr-open` 6. PR approved: - `status:approved` 7. PR merged but issue still needs closure/reconciliation: - `status:reconcile` 8. Issue fully complete: - `status:done` 9. Duplicate issue: - `status:duplicate` 10. Discussion-only issue: - `type:discussion` - usually `status:triage`, `status:ready`, or `status:done` depending on whether a conclusion/action has been reached ## Discussion issue rules Discussion issues must be labeled `type:discussion`. A discussion issue should not be treated as implementation-ready unless it also has a clear implementation status and next action. If a discussion produces implementation work, either: 1. convert the discussion issue into an implementation issue by changing labels and adding acceptance criteria, or 2. create child implementation issues and leave the discussion issue as `type:discussion`. ## MCP/tooling requirements Add tooling or validation so that issue creation and workflow transitions enforce labels. Required behavior: - Creating an issue should require or recommend a `type:*` label. - Creating an issue should require or recommend an initial `status:*` label. - Discussion issues must receive `type:discussion`. - Moving an issue to in-progress should replace the old `status:*` label with `status:in-progress`. - Opening a PR that closes an issue should move the issue to `status:pr-open`. - Approved PRs should move linked issues to `status:approved` if appropriate. - Merged PRs should move linked issues to `status:reconcile` or `status:done` depending on the workflow. - Duplicate closures should apply `status:duplicate`. ## Acceptance criteria 1. Define the canonical `type:*` and `status:*` label taxonomy in documentation. 2. Add or update templates so new issues include correct labels. 3. Add workflow validation to detect issues missing: - a `type:*` label - a `status:*` label 4. Add validation that discussion issues are labeled `type:discussion`. 5. Add validation that more than one `status:*` label is not active unless explicitly allowed. 6. Add tool/helper behavior to transition status labels during: - claim - start work - block - PR open - approval - merge - reconciliation - duplicate closure 7. Add tests covering: - valid labeled issue - issue missing `type:*` - issue missing `status:*` - discussion issue missing `type:discussion` - multiple conflicting `status:*` labels - status transition removes old status label - PR-open transition applies `status:pr-open` - duplicate transition applies `status:duplicate` 8. Ensure existing issue, PR, reviewer, merger, and reconciler workflows still pass. ## Out of scope - Replacing thread comments. - Replacing `[CONTROLLER HANDOFF]` or `[THREAD STATE LEDGER]`. - Weakening role permissions. - Automatically closing issues without controller/reconciler rules. ## Desired outcome The issue queue should be readable at a glance. A human or LLM should be able to scan labels and immediately know: - what kind of issue it is - whether it is discussion-only or implementation-ready - where it is in the workflow - what class of actor should touch it next

jcwalker3 added the status:in-progress label 2026-07-08 03:07:01 -05:00

jcwalker3 commented

2026-07-08 03:07:01 -05:00

Issue claim heartbeat

kind: claim
issue: Require issue type and workflow status labels (#513)
branch: codex/issue-513-workflow-labels
phase: claimed
profile: prgs-author
pr: none
blocker: none
next_action: create worktree and begin implementation

**Issue claim heartbeat** - kind: claim - issue: #513 - branch: codex/issue-513-workflow-labels - phase: claimed - profile: prgs-author - pr: none - blocker: none - next_action: create worktree and begin implementation

jcwalker3 referenced this issue from a commit

2026-07-08 03:21:04 -05:00

feat: require workflow labels for issues (Closes #513)

jcwalker3 referenced a pull request that will close this issue

2026-07-08 03:21:33 -05:00

feat: require issue type and workflow status labels (Closes #513) #518

sysadmin referenced this issue

2026-07-08 21:24:02 -05:00

feat: require issue type and workflow status labels (Closes #513) #518

sysadmin referenced this issue

2026-07-08 21:24:26 -05:00

feat: require issue type and workflow status labels (Closes #513) #518