Goal
Define the vocabulary and operating model for Gira state after the 2.0 control-plane work, so users can understand which states are GitHub labels, which are computed JSON, which are durable receipts/comments, and which are local config/cache.
Scope
Planning and documentation only. Produce a concrete state model and UX vocabulary proposal before adding more features. Cover:
- label-backed state such as
status:*, type:*, priority:*, area:*, agent:*, and optional lane:*
- computed state such as readiness, blockers, queue membership, next actions, goal stop reasons, and adapter approval classes
- receipt/comment-backed state such as finish receipts, goal finish handoffs, supersede decisions, and worker handoff notes
- local state such as workspace config, repo registry, branch-policy records, cache, and machine-local overrides
- how to explain
goal versus milestone, epic, ticket, workspace queue, and PR
- what should remain CLI/JSON contract and what should later become 3.0 UI surface
Do not implement new behavior in this issue unless the planning result explicitly creates follow-up implementation tickets.
Acceptance Criteria
- A concise state ownership table exists in docs, separating GitHub labels, computed JSON state, receipt/comment state, and local config/cache.
- The docs explain why Gira should avoid turning every computed state into a GitHub label.
- The docs explain
goal in relation to milestone, epic, ticket, workspace queue, and PR using user-facing language.
- The planning result proposes the next UX/documentation follow-up issues, if any.
go test ./... and sh scripts/check-docs-contract.sh . pass if docs are changed.
Doctor Impact
No runtime doctor, audit, status, finish, branch policy, provider, or workflow behavior changes are expected. This is a planning/documentation issue.
Delivery Mode
Planning-first. Start only when ready to write the state-model proposal. Use one branch and one PR if the planning output is committed to docs. Do not start feature implementation from this issue.
Notes
Related: #521, #525
base_branch: main
base_source: branch_policy.default
branch_policy_mode: github-flow
target: default
work_branch: issue-633-planning-clarify-gira-state-model-and-goal-ux-vocabulary
Goal
Define the vocabulary and operating model for Gira state after the 2.0 control-plane work, so users can understand which states are GitHub labels, which are computed JSON, which are durable receipts/comments, and which are local config/cache.
Scope
Planning and documentation only. Produce a concrete state model and UX vocabulary proposal before adding more features. Cover:
status:*,type:*,priority:*,area:*,agent:*, and optionallane:*goalversus milestone, epic, ticket, workspace queue, and PRDo not implement new behavior in this issue unless the planning result explicitly creates follow-up implementation tickets.
Acceptance Criteria
goalin relation to milestone, epic, ticket, workspace queue, and PR using user-facing language.go test ./...andsh scripts/check-docs-contract.sh .pass if docs are changed.Doctor Impact
No runtime doctor, audit, status, finish, branch policy, provider, or workflow behavior changes are expected. This is a planning/documentation issue.
Delivery Mode
Planning-first. Start only when ready to write the state-model proposal. Use one branch and one PR if the planning output is committed to docs. Do not start feature implementation from this issue.
Notes
Related: #521, #525
base_branch: main
base_source: branch_policy.default
branch_policy_mode: github-flow
target: default
work_branch: issue-633-planning-clarify-gira-state-model-and-goal-ux-vocabulary