feat: [Planning] Clarify Gira state model and goal UX vocabulary#634
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive 'State Model' documentation that defines the boundaries between GitHub labels, computed JSON state, durable receipts, and local cache. The changes include new documentation files and updates to existing ones to ensure a consistent understanding of state ownership. The review feedback focuses on improving technical precision, specifically by clarifying the definition of 'Goal' objects, ensuring consistency between documentation and CLI flag naming conventions, and aligning JSON key examples across different documentation files.
| | PR | The reviewable change unit and main implementation evidence for a ticket. | A ticket by itself. | | ||
| | Milestone | A time, phase, sprint, or release boundary. It groups work. | A delegation envelope. | | ||
| | Epic | A large GitHub issue that groups related work. It can remain human-managed. | Automatically an autonomous goal. | | ||
| | Goal | A large objective that Gira treats as an autonomy envelope over child tickets, stop conditions, and finish receipts. | A GitHub-native object or milestone. | |
There was a problem hiding this comment.
The description in the 'Not the same as' column for Goal is slightly ambiguous since Goals are implemented as GitHub Issues (which are native objects). Clarifying that it is distinct from native Milestones or Project-only items would be more precise.
| | Goal | A large objective that Gira treats as an autonomy envelope over child tickets, stop conditions, and finish receipts. | A GitHub-native object or milestone. | | |
| | Goal | A large objective that Gira treats as an autonomy envelope over child tickets, stop conditions, and finish receipts. | A native GitHub Milestone or Project-only item. | |
| Adapter runtimes should use command capability metadata and | ||
| `gira-approval-plan/v1` instead of guessing whether a command is safe. A dry-run | ||
| approval for one command must not authorize a different command, repo, issue, | ||
| branch, or flag set. |
There was a problem hiding this comment.
Use underscores for human_review and ready_to_release to maintain consistency with the CLI flag values (e.g., --terminal human_review) and other machine-readable identifiers used in the documentation.
| branch, or flag set. | |
| - Whether completion is done, human_review, ready_to_release, blocked, superseded, or abandoned. |
| | --- | --- | --- | | ||
| | GitHub labels | `status:ready`, `status:in-progress`, `status:in-review`, `status:blocked`, `status:done`, `type:*`, `priority:*`, `area:*`, `agent:*` | Public state humans can scan in GitHub. | | ||
| | GitHub evidence | Issues, PRs, checks, reviews, milestones, comments, closing references. | Durable proof of work and completion. | | ||
| | Gira JSON | `ticket_readiness`, `pr_readiness`, `finish-readiness/v1`, `workspace-queues/v1`, `goal-next/v1`, blockers, next steps. | Rich computed state for CLI, agents, adapters, and future UI. | |
There was a problem hiding this comment.
The example next steps uses a space, but the corresponding JSON key is next_step (as seen in the main docs/state-model.md file). It should be updated for consistency with the actual JSON schema.
| | Gira JSON | `ticket_readiness`, `pr_readiness`, `finish-readiness/v1`, `workspace-queues/v1`, `goal-next/v1`, blockers, next steps. | Rich computed state for CLI, agents, adapters, and future UI. | | |
| | Gira JSON | ticket_readiness, pr_readiness, finish-readiness/v1, workspace-queues/v1, goal-next/v1, blockers, next_step. | Rich computed state for CLI, agents, adapters, and future UI. | |
StatPan
deleted the
issue-633-planning-clarify-gira-state-model-and-goal-ux-vocabulary
branch
1 participant
Closes #633