From 846e56277e30b3160f799a2d83e89aeefb93c7b6 Mon Sep 17 00:00:00 2001 From: StatPan Date: Sat, 23 May 2026 23:20:30 +0900 Subject: [PATCH] Document Gira state model and goal vocabulary --- README.md | 2 +- docs-site/.vitepress/config.mts | 1 + docs-site/goal-mode.md | 3 +- docs-site/state-model.md | 55 +++++++++++ docs-site/workspace.md | 1 + docs/goal-operating-model.md | 3 + docs/state-model.md | 159 ++++++++++++++++++++++++++++++++ docs/workspace.md | 3 + 8 files changed, 225 insertions(+), 2 deletions(-) create mode 100644 docs-site/state-model.md create mode 100644 docs/state-model.md diff --git a/README.md b/README.md index ece678a..0fa1b78 100644 --- a/README.md +++ b/README.md @@ -678,7 +678,7 @@ GIRA_INSTALL_DIR="${tmpdir}" GIRA_VERSION=v1.0.0 sh install.sh The release policy and package-manager channel details are documented in [docs/release-distribution.md](docs/release-distribution.md). Developer experience conventions for first-run onboarding, dry-run/apply output, JSON, recovery, and the issue-to-PR loop are documented in [docs/dx.md](docs/dx.md). -The GitHub-native Product OS schema for future Projects v2 planning, roadmap date semantics, permission/secret model, and dry-run-first automation is documented in [docs/product-os-schema.md](docs/product-os-schema.md). The execution roadmap for that phase is tracked in [docs/product-os-roadmap.md](docs/product-os-roadmap.md). The Jira-vs-Gira operating boundary, work decomposition contract, and assistant/dev-agent split are documented in [docs/jira-gira-operating-boundary.md](docs/jira-gira-operating-boundary.md). Goal-level autonomy for long-running agent work is documented in [docs/goal-operating-model.md](docs/goal-operating-model.md). Jira-primary provider mode and workflow safety are documented in [docs/jira-primary-provider.md](docs/jira-primary-provider.md). Closure Funnel stats are documented in [docs/closure-funnel-stats.md](docs/closure-funnel-stats.md). Agent delegation lanes, approval policy, and Delegation Quality metrics are documented in [docs/agent-delegation-lanes.md](docs/agent-delegation-lanes.md). The workspace backlog layer is documented in [docs/workspace.md](docs/workspace.md), business-group multi-repo workflow design is documented in [docs/business-group-workflows.md](docs/business-group-workflows.md), and the older portfolio intake compatibility layer is documented in [docs/portfolio-intake.md](docs/portfolio-intake.md). The vendor-neutral dashboard/export boundary for Notion and other consumers is documented in [docs/dashboard-consumer-contract.md](docs/dashboard-consumer-contract.md), and the first concrete export bundle layout is documented in [docs/dashboard-export-artifacts.md](docs/dashboard-export-artifacts.md). The hosted control-plane product boundary and service roadmap are documented in [docs/hosted-control-plane-roadmap.md](docs/hosted-control-plane-roadmap.md). The MVP CRUD support contract is documented in [docs/crud-capability-matrix.md](docs/crud-capability-matrix.md). Adoption on pre-configured repositories is documented in [docs/adoption-migration-playbook.md](docs/adoption-migration-playbook.md). +The GitHub-native Product OS schema for future Projects v2 planning, roadmap date semantics, permission/secret model, and dry-run-first automation is documented in [docs/product-os-schema.md](docs/product-os-schema.md). The execution roadmap for that phase is tracked in [docs/product-os-roadmap.md](docs/product-os-roadmap.md). The Gira state ownership model for labels, computed JSON state, receipts, and local cache is documented in [docs/state-model.md](docs/state-model.md). The Jira-vs-Gira operating boundary, work decomposition contract, and assistant/dev-agent split are documented in [docs/jira-gira-operating-boundary.md](docs/jira-gira-operating-boundary.md). Goal-level autonomy for long-running agent work is documented in [docs/goal-operating-model.md](docs/goal-operating-model.md). Jira-primary provider mode and workflow safety are documented in [docs/jira-primary-provider.md](docs/jira-primary-provider.md). Closure Funnel stats are documented in [docs/closure-funnel-stats.md](docs/closure-funnel-stats.md). Agent delegation lanes, approval policy, and Delegation Quality metrics are documented in [docs/agent-delegation-lanes.md](docs/agent-delegation-lanes.md). The workspace backlog layer is documented in [docs/workspace.md](docs/workspace.md), business-group multi-repo workflow design is documented in [docs/business-group-workflows.md](docs/business-group-workflows.md), and the older portfolio intake compatibility layer is documented in [docs/portfolio-intake.md](docs/portfolio-intake.md). The vendor-neutral dashboard/export boundary for Notion and other consumers is documented in [docs/dashboard-consumer-contract.md](docs/dashboard-consumer-contract.md), and the first concrete export bundle layout is documented in [docs/dashboard-export-artifacts.md](docs/dashboard-export-artifacts.md). The hosted control-plane product boundary and service roadmap are documented in [docs/hosted-control-plane-roadmap.md](docs/hosted-control-plane-roadmap.md). The MVP CRUD support contract is documented in [docs/crud-capability-matrix.md](docs/crud-capability-matrix.md). Adoption on pre-configured repositories is documented in [docs/adoption-migration-playbook.md](docs/adoption-migration-playbook.md). This repository dogfoods Gira for its own work. The active operating loop, sprint commands, and maintainer handoff are documented in [docs/dogfood.md](docs/dogfood.md). diff --git a/docs-site/.vitepress/config.mts b/docs-site/.vitepress/config.mts index c10dcc1..219fef5 100644 --- a/docs-site/.vitepress/config.mts +++ b/docs-site/.vitepress/config.mts @@ -47,6 +47,7 @@ export default defineConfig({ items: [ { text: 'Workspace', link: '/workspace' }, { text: 'Ticket Workflow', link: '/ticket-workflow' }, + { text: 'State Model', link: '/state-model' }, { text: 'Goal Mode', link: '/goal-mode' }, { text: 'Sprint And Release', link: '/sprint-release' }, { text: 'Readiness And Audit', link: '/readiness-audit' }, diff --git a/docs-site/goal-mode.md b/docs-site/goal-mode.md index 3788d63..801b4a8 100644 --- a/docs-site/goal-mode.md +++ b/docs-site/goal-mode.md @@ -64,4 +64,5 @@ historical evidence, or duplicate an existing handoff receipt. Use `gira epic list` for numberless discovery of `type:epic` issues. Use [Sprint And Release](/sprint-release) when the boundary is a GitHub milestone -rather than a goal issue. +rather than a goal issue. Use [State Model](/state-model) for the distinction +between labels, computed goal state, receipts, and local cache. diff --git a/docs-site/state-model.md b/docs-site/state-model.md new file mode 100644 index 0000000..ffc4e62 --- /dev/null +++ b/docs-site/state-model.md @@ -0,0 +1,55 @@ +# State Model + +Gira keeps GitHub as the source of truth, but it does not turn every operating +condition into a GitHub label. + +The state model is: + +```text +GitHub labels = small public workflow taxonomy +Gira JSON = computed operating state +GitHub comments = durable receipts and handoffs +Local files/cache = configuration, bindings, and acceleration +``` + +## Ownership + +| Owner | Examples | Use | +| --- | --- | --- | +| 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. | +| Receipts | `finish-receipt/v1`, `goal-finish-receipt/v1`, supersede notes, handoff notes. | Durable audit comments explaining a decision. | +| Local config/cache | Workspace registry, repo registry, branch policy records, cache. | Ergonomics and performance, not hidden completion state. | + +## Why Not More Labels? + +Labels should stay few and stable. Conditions like `finish_ready`, +`review_needed`, `failed_check`, `missing_review`, or +`human_review_handoff_present` are computed from richer evidence. If each became +a label, the label taxonomy would drift and operators would need to clean up +labels that Gira can already calculate. + +Use labels for coarse workflow state. Use JSON for precise operating state. + +## Goal Vocabulary + +| Term | Meaning | +| --- | --- | +| Ticket | One executable work packet, normally one branch and one PR. | +| PR | Reviewable change and implementation evidence. | +| Milestone | Time, phase, sprint, or release grouping. | +| Epic | Large GitHub issue that groups work. | +| Goal | A GitHub issue that Gira interprets as delegated multi-ticket work with child tickets, stop conditions, and finish receipts. | +| Workspace queue | Computed view over many tickets and PRs, such as agent-ready or review-needed. | + +`goal next` does not mean milestone next. It means: choose the next safe child +ticket inside a delegated goal issue, or stop with a human-review reason. + +## Future UI Boundary + +The CLI and JSON contracts are the computation layer. Future UI should render +goal graphs, workspace queues, finish evidence, and blockers from these +contracts instead of creating a second workflow model. + +Canonical source: [docs/state-model.md](https://github.com/StatPan/gira/blob/main/docs/state-model.md). diff --git a/docs-site/workspace.md b/docs-site/workspace.md index b67f70d..fcbf9f6 100644 --- a/docs-site/workspace.md +++ b/docs-site/workspace.md @@ -74,5 +74,6 @@ finish mutations. - [Global Config](/global-config) - [Ticket Workflow](/ticket-workflow) +- [State Model](/state-model) - [Readiness And Audit](/readiness-audit) - [Command Reference](/command-reference) diff --git a/docs/goal-operating-model.md b/docs/goal-operating-model.md index 59769e3..5513601 100644 --- a/docs/goal-operating-model.md +++ b/docs/goal-operating-model.md @@ -195,3 +195,6 @@ Minimum viable GitHub mapping: Future slices may add a compact machine-readable block in goal comments, but the readable GitHub issue should remain sufficient for humans to audit the goal without a Gira database. + +For the broader ownership boundary between GitHub labels, computed JSON state, +durable receipts, and local cache, see [Gira State Model](state-model.md). diff --git a/docs/state-model.md b/docs/state-model.md new file mode 100644 index 0000000..1ae96cf --- /dev/null +++ b/docs/state-model.md @@ -0,0 +1,159 @@ +# Gira State Model + +Gira should keep durable workflow state on the GitHub object that already owns +the evidence. It should not turn every derived condition into a label, and it +should not create a hidden local planning database. + +The practical rule is: + +```text +GitHub labels = small public workflow taxonomy +Gira JSON = computed operating state +GitHub comments = durable receipts and handoffs +Local files/cache = configuration, bindings, and acceleration +``` + +## State Ownership + +| State owner | Examples | Purpose | Source of truth | +| --- | --- | --- | --- | +| GitHub labels | `status:ready`, `status:in-progress`, `status:in-review`, `status:blocked`, `status:done`, `type:*`, `priority:*`, `area:*`, `agent:*`, optional `lane:*` | Small public taxonomy that humans can scan in GitHub. | GitHub issue labels. | +| GitHub issue/PR state | Open or closed issue, linked PR, draft PR, merged PR, reviews, checks, milestones, assignees, comments. | Durable execution evidence. | GitHub issue, PR, check, review, milestone, and comment APIs. | +| Gira computed JSON | `ticket_readiness`, `pr_readiness`, `finish-readiness/v1`, `workspace-queues/v1`, `goal-next/v1`, `blockers`, `reason_codes`, `next_action`, `next_step`, `remaining_autonomous_work`. | High-cardinality operating state for agents, adapters, dashboards, and CLI decisions. | Recomputed from GitHub evidence and Gira config. | +| Receipt/comment state | `finish-receipt/v1`, `goal-finish-receipt/v1`, supersede decision notes, worker handoff notes, progress notes. | Durable audit trail that explains why a transition or handoff happened. | GitHub issue or PR comments. | +| Local or global config | `.gira/config.yaml`, global repo registry, workspace registry, branch policy defaults, provider config pointers. | Operator configuration and repo/workspace selection. | Local files unless explicitly committed as repo-local contract. | +| Local cache/state | Workspace status cache, API budget-friendly snapshots, recent command state, checkout path metadata. | Speed and ergonomics only. | Disposable local cache; never the authoritative workflow state. | +| Adapter approval evidence | `gira-approval-plan/v1`, command capability metadata, planned actions, post-apply verification command. | Machine-readable approval boundary before a matching `--apply`. | Dry-run JSON output stored by the adapter or operator. | + +## Label-Backed State + +Labels should remain few, stable, and useful in the GitHub UI. + +The core status labels are: + +| Label | Meaning | +| --- | --- | +| `status:ready` | A ticket can be started after normal readiness checks. | +| `status:in-progress` | Work has started, usually with a trusted branch. | +| `status:in-review` | A PR or review surface is active. | +| `status:blocked` | External dependency, decision, or policy blocks progress. | +| `status:done` | Completion was accepted through merge, close, supersede, or explicit receipt evidence. | + +Other stable label families: + +- `type:*` for issue kind. +- `priority:*` for coarse priority. +- `area:*` or future `layer:*` for product or implementation area. +- `agent:*` for execution actor class, not a replacement for assignees. +- `lane:*` for delegation authority when a repo opts into agent lanes. + +Gira should avoid labels such as `status:finish-ready`, +`status:review-needed`, `status:failed-check`, `status:human-decision`, or +`status:missing-receipt`. Those are computed views over richer evidence, and +making them labels would create drift and taxonomy churn. + +## Computed State + +Computed state is where Gira can be expressive without polluting GitHub labels. + +| Computed state | Derived from | Used by | +| --- | --- | --- | +| `ticket-readiness/v1` | Issue body, labels, state, scope, acceptance criteria, policy. | `ticket status`, `workspace_queues`, worker handoff. | +| `pr-readiness/v1` | Linked PR, draft state, checks, reviews, closing reference, branch binding. | `ticket review`, `ticket finish`, review queues. | +| `finish-readiness/v1` | Ticket status, linked PR, checks, review, labels, branch trust, telemetry. | `ticket finish --dry-run`. | +| `workspace-queues/v1` | Workspace issue summaries plus targeted ticket status details. | Multi-repo operator queues and future UI dashboards. | +| `goal-status/v1` and `goal-next/v1` | Goal issue, child issue links, child ticket state, PR evidence, receipts. | Long-running agent delegation and stop decisions. | +| Adapter capability and approval reports | Command registry, dry-run result, planned actions. | Durable agent runtimes and approval gates. | + +Computed state can have many values because it is not a GitHub taxonomy. It can +name precise blockers such as `missing_linked_pr`, `checks_failed`, +`missing_review`, `child_524_missing_finish_receipt`, or +`human_review_handoff_present` without asking users to maintain those as labels. + +## Receipt And Comment State + +Some state is too important to be only computed, but too contextual to be a +label. That belongs in a durable GitHub comment. + +Use comments for: + +- Finish receipts that explain why ticket completion was accepted. +- Goal finish receipts and human-review handoffs. +- Supersede decisions and replacement links. +- Worker handoff notes that preserve context between agents or humans. +- Progress, blocker, and decision notes that are useful audit evidence. + +Receipts should be idempotent where possible. Gira should not create duplicate +goal handoff receipts when an existing `goal-finish-receipt/v1` comment already +records the same terminal state. + +## Local State + +Local state is allowed, but it must not become the hidden source of truth for +workflow completion. + +Appropriate local state: + +- Repo and workspace registry entries. +- Checkout path and default workspace selection. +- Branch policy defaults and recorded branch binding evidence. +- Cache entries for bounded workspace reads. +- Provider configuration pointers that do not contain secrets. + +Inappropriate local state: + +- "This issue is done" without GitHub close/merge/receipt evidence. +- Hidden ticket queues that disagree with labels and PR state. +- Agent-only completion decisions that are not written back to GitHub. + +If local state disappears, Gira should be able to reconstruct the workflow from +GitHub plus repo/global configuration, possibly with less performance or less +ergonomic command resolution. + +## Vocabulary + +| Term | User-facing explanation | Not the same as | +| --- | --- | --- | +| Ticket | One executable work packet. It has one primary branch and usually one primary PR. | A goal or a milestone. | +| 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. | +| Workspace queue | A computed operating view over many tickets and PRs. | A label taxonomy or hidden backlog database. | +| Receipt | A durable comment explaining a transition, completion, supersede, or handoff decision. | A status label. | + +The shortest explanation for goal mode is: + +> A goal is a GitHub issue that Gira interprets as delegated multi-ticket work. +> `goal next` chooses the next safe child ticket, and `goal finish` records +> convergence or human-review handoff evidence. + +## UI And Adapter Boundary + +The CLI and JSON contracts should remain the computation layer. Future 3.0 UI +or hosted surfaces should render the same state instead of reimplementing it. + +Good UI candidates: + +- Goal graph summary and why `goal next` stopped. +- Workspace queues with blockers and next safe commands. +- Ticket detail evidence cards. +- Finish readiness and receipt review. +- Drift and missing evidence dashboards. + +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. + +## Follow-Up Planning Candidates + +This state model suggests these follow-up issues: + +- Improve human-readable goal summaries, possibly `gira goal brief`. +- Add a compact state-model page to `gira guide` if users keep confusing labels, + computed state, receipts, and cache. +- Audit legacy docs for wording that implies local cache or Projects are the + source of truth. +- Decide whether future `lane:*` labels should be part of the default taxonomy + or opt-in delegation policy only. diff --git a/docs/workspace.md b/docs/workspace.md index 5fec69c..26ab808 100644 --- a/docs/workspace.md +++ b/docs/workspace.md @@ -243,6 +243,9 @@ hosted view can render the same queues across workspaces, but GitHub issues and PRs remain the source of truth and mutation still flows through explicit Gira commands. +For the broader ownership boundary between labels, computed JSON state, +receipts, and local cache, see [Gira State Model](state-model.md). + ## Boundary This is not a separate Jira import/export database. Workspace commands operate on issues, labels, milestones, and links that remain visible in GitHub. `gira projects sync` links and mirrors repository issue state into an existing GitHub Project; repo issues, labels, and milestones remain the source of truth. It mirrors `priority:*` labels to `Priority`, `area:*` labels to `Layer / workstream`, `agent:*` labels to `Owner / agent`, status labels to `Status`, and milestone due dates to `Target date`.