cc-os/openspec/specs/issue-state-labels/spec.md

issue-state-labels

ADDED Requirements

Requirement: Canonical label taxonomy

The backlog label set on every routed tracker SHALL be: priority P0 P1 P2 P3; autonomy hitl semi afk-ready; state next waiting review. /os-backlog:route SHALL ensure these labels exist (idempotently) on forgejo/github trackers when onboarding. No doing or done label exists: in-progress is expressed by assignment/branch activity, completion by closing the issue.

Scenario: Route onboards a Forgejo repo

• WHEN /os-backlog:route configures tracker=forgejo:<owner>/<repo>
• THEN all ten canonical labels exist on the repo afterwards, and re-running route creates nothing new

Requirement: The next label is human-only

The next label marks human-curated priority. The AI SHALL never apply or remove next on any issue, in any project, under any instruction short of an explicit direct user request naming the specific issue.

Scenario: AI triages a backlog

• WHEN an AI session labels or files issues during triage or capture
• THEN next is neither added to nor removed from any issue

Requirement: Autonomy label semantics

hitl issues are human-owned and SHALL never be picked up autonomously. semi issues MAY be worked autonomously through their mechanical parts, SHALL stop at named decision gates, and on shipping SHALL receive the review label instead of being closed. afk-ready issues, once shipped AND verified, SHALL be closed directly. Assigning autonomy labels is the responsible project's job; ambiguity resolves to hitl.

Scenario: Semi-autonomy work ships

• WHEN an AI session completes the mechanical work of a semi issue
• THEN the issue receives the review label, a comment summarizing what shipped, and remains open for human sign-off

Scenario: Afk-ready work ships and verifies

• WHEN an AI session completes and verifies work on an afk-ready issue
• THEN the issue is closed with a closing comment linking the verification evidence

Requirement: Working an issue means recording state on it

An AI session working an issue SHALL record state transitions on the issue itself: a comment when work starts, the waiting label plus a blocker comment when blocked, and the shipping transition per its autonomy label. Blocked issues SHALL have waiting removed when work resumes.

Scenario: Work blocks on an external dependency

• WHEN in-progress issue work hits a blocker the session cannot resolve
• THEN the issue gains the waiting label and a comment naming the blocker, and the session moves on

Requirement: Recurring process issues are never closed

An issue representing a recurring process (e.g. the biweekly orchestration audit in the ops repo) SHALL be worked by commenting each occurrence's outcome on it and leaving it open; closing it is a human-only action.

Scenario: Recurring audit completes an occurrence

• WHEN an AI session completes one occurrence of a recurring-convention issue
• THEN the outcome is added as a comment and the issue stays open with its labels unchanged