[Milestone Proposal] Gira 2.0: evidence-backed agent workflow control plane

[StatPan]

Goal

Define the Gira 2.0 milestone direction before creating GitHub milestones and slicing implementation issues.

Gira 2.0 should move from a ticket lifecycle CLI into a GitHub-native control plane that helps human and AI workers converge software work against the original goal, review evidence, checks, and finish policy.

Product Thesis

Gira 2.0 is not an AI coding agent, Jira clone, or generic GitHub wrapper.

It should be the GitHub-native workflow contract that turns AI-assisted work into reviewable, auditable, evidence-backed completion.

Core loop:

issue -> branch -> PR -> checks -> review -> evidence -> finish

The important question is not only "did an agent write code?" but:

• Was the issue executable as a work order?
• Did the PR satisfy the original goal and acceptance criteria?
• Did checks, review, labels, and linked state converge?
• Is there enough evidence to finish?
• Can the next safe command be determined from state?

Proposed 2.0 Milestones

2.0 Alpha: State-Aware Ticket Runtime

Make Gira feel stateful in the common path. Users should not need to pass issue and PR numbers when they are already on the relevant branch or linked PR context.

Representative capabilities:

• current ticket and PR resolution from branch/workspace state
• gira ticket review as a state-aware reviewer packet
• ticket prompt role packets for planner, implementer, and reviewer
• deterministic issue/PR/evidence JSON packet
• stronger action-oriented errors when context is missing or ambiguous
• repo-local guidance such as AGENTS.md surfaced in prompts where useful

Done when:

• common ticket commands work from current state without explicit numbers
• reviewer packet can be handed directly to an AI review worker
• prompt JSON is stable enough for automation wrappers

2.0 Beta: Evidence-Based Finish and Audit

Turn finish into an evidence-backed convergence step, not only a merge helper.

Representative capabilities:

• completion drift audit
• status:done and active status normalization
• finish readiness report
• finish receipt comment
• provenance and AI delivery telemetry validation
• acceptance criteria and evidence gap surfacing
• workflow nonconformance detection for linked issue/PR/check/review state

Done when:

• Gira can explain why a ticket can or cannot finish
• closed/merged work converges to consistent labels and issue state
• unknown provenance and missing evidence are visible in reports

2.0 RC: Goal Mode

Introduce a goal as an autonomy envelope for long-running AI-assisted work.

Representative capabilities:

• gira goal plan
• gira goal next
• gira goal status
• gira goal finish
• child ticket graph over GitHub issues
• stop conditions and human decision points
• goal finish receipt across child tickets and PRs

Done when:

• a larger objective can be decomposed into executable tickets
• Gira can identify the next safe child ticket or explain why it must stop
• goal completion is backed by linked issue, PR, check, review, and receipt evidence

2.0 GA: Workspace Health and Agent Queues

Provide a multi-repo read-only operating view for AI-assisted delivery.

Representative capabilities:

• gira workspace status
• gira workspace scan --json
• agent-ready queue
• review-needed queue
• finish-ready queue
• failed-check and blocked-PR queues
• Closure Funnel workspace rollup
• provider health and Jira-primary readiness where configured
• stable export/report artifacts suitable for a future hosted service

Done when:

• a team can see what agents can work on, what humans must review, what can finish, and where workflow drift exists
• workspace JSON can serve as the read-only foundation for hosted Gira v0

Main Product Axes

1. Work Order Quality

Issues should be executable work packets with goal, scope, acceptance criteria, labels, risk, and expected delivery/review/merge mode.

Target capabilities:

• ticket readiness checks
• structured issue packet generation
• provenance and verification sections in new tickets
• missing context diagnostics

2. Context Packets

Gira should reconstruct the right context for stateless agents.

Target capabilities:

• planner, implementer, and reviewer packets
• current-state resolution
• PR/check/evidence context
• repo-local rules and AGENTS.md reminders
• JSON contracts for automation

3. Evidence and Finish

Completion should be proven by GitHub evidence.

Target capabilities:

• finish readiness
• finish receipt
• closing reference validation
• check/review blocker reporting
• acceptance/evidence gap detection

4. Audit and Drift

Gira should detect workflow nonconformance.

Target capabilities:

• closed issue with active status label
• open issue with done status
• multiple status labels
• merged PR with non-converged issue
• in-review issue without linked PR
• AI-executed work without provenance or evidence

5. Goal Autonomy

A goal should define what agents may do, when they must stop, and what receipt proves convergence.

Target capabilities:

• goal planning
• next safe work selection
• stop conditions
• child ticket evidence graph
• goal receipt

6. Workspace Readiness

Teams need operating queues and health reports, not personal productivity leaderboards.

Target capabilities:

• agent-ready queue
• review queue
• finish queue
• stale/blocked/failed-check queue
• Closure Funnel workspace rollup
• provider health reports

Explicit Non-Goals

• Do not become a Jira clone.
• Do not become an AI code editor.
• Do not rank individual humans or agents.
• Do not use labels as a high-cardinality telemetry store.
• Do not introduce a hidden planning database as the source of truth.
• Do not auto-merge or mutate provider state without explicit dry-run/apply or future approval gates.

Initial Follow-Up Issues To Create

• State-aware ticket resolver hardening
• Review packet output contract and goal-fulfillment verdict schema
• Finish receipt format
• Workflow drift audit command
• Goal mode first slice
• Workspace status JSON contract
• Agent/review/finish queue definitions

Suggested GitHub Milestone Layout

• 2.0 Alpha - State-Aware Ticket Runtime
• 2.0 Beta - Evidence-Based Finish and Audit
• 2.0 RC - Goal Mode
• 2.0 GA - Workspace Health and Agent Queues

Acceptance Criteria For This Planning Proposal

• Maintainer reviews and adjusts the 2.0 milestone names.
• The four proposed milestone buckets are created in GitHub or converted into a smaller set.
• Follow-up implementation issues are created under the chosen milestones.
• Existing completed work is mapped into the closest 2.0 axis where useful.
• The public product framing is updated after the milestone shape stabilizes.

Product Framing

Gira 2.0 should be described as:

A GitHub-native control plane that turns human and AI work into reviewable, auditable, evidence-backed completion.

Short version:

Work-order to PR to evidence to finish.

[StatPan]

Thanks, this is a useful framing.

I agree that the key Gira 2.0 object is not just the issue/PR link, but a completion receipt that a maintainer or operator can audit without trusting the agent transcript.

For the public OSS roadmap, I will probably keep the language around completion receipt or finish receipt rather than buyer-specific terminology. The receipt should include the original issue goal and acceptance criteria, linked PR/check/review evidence, known gaps or unchecked areas, and the final finish decision.

I will fold this into the 2.0 Beta track for evidence-based finish and audit. Paid review is not needed at this stage, but the framing is helpful.

[StatPan]

Progress update:

• Implemented first-class milestone lifecycle support in [Task] Add first-class milestone lifecycle and bulk ticket assignment #524 / feat: [Task] Add first-class milestone lifecycle and bulk ticket assignment #526.
• Created the four proposed Gira 2.0 GitHub milestones using gira milestone new after dry-run review:
  • 2.0 Alpha - State-Aware Ticket Runtime
  • 2.0 Beta - Evidence-Based Finish and Audit
  • 2.0 RC - Goal Mode
  • 2.0 GA - Workspace Health and Agent Queues
• Mapped the completed milestone-lifecycle work ([Task] Add first-class milestone lifecycle and bulk ticket assignment #524) into 2.0 Alpha - State-Aware Ticket Runtime.

I am keeping this planning proposal open because follow-up implementation issues still need to be sliced under the chosen milestones, and the public product framing should be updated after that shape stabilizes.

[StatPan]

Roadmap refinement: keep monetization strategy outside, but build the primitives now

Related strategic backlog note: StatPan/backlog#19

The monetization/backend-independence discussion should not be copied directly into this public 2.0 roadmap yet. Gira 2.0 should stay focused on public OSS implementation value:

CLI-first, GitHub-first, evidence-backed completion control plane.

However, the 2.0 milestone can still build the product primitives that make future hosted, enterprise, GitLab, Forgejo, or commercial packaging possible.

What belongs in this Gira 2.0 roadmap

Public implementation issues should stay concrete and user-facing:

• state-aware ticket/PR resolution
• milestone/work-batch lifecycle
• review packet contract
• finish readiness and finish receipt
• drift audit
• workspace status JSON
• agent/review/finish queue definitions
• deterministic JSON outputs
• dry-run/apply mutation behavior
• docs and command reference updates

These are valuable for OSS users now and also become future product surfaces later.

What should stay in backlog for now

Keep these out of the public Gira roadmap until the implementation shape is clearer:

• monetization hypotheses
• hosted dashboard packaging
• enterprise self-managed packaging
• GitLab/Forgejo backend strategy
• licensing/commercial boundary
• sovereign delivery kit positioning
• private product strategy

Design pressure to preserve now

Even while Gira remains GitHub-first, implementation should avoid unnecessary GitHub-only coupling where it does not improve UX.

Useful constraints:

• Treat milestones as work-batch boundaries, not only a GitHub field.
• Keep source-of-truth state in GitHub for the public path.
• Prefer deterministic JSON contracts that could later power UI/hosted views.
• Keep evidence summaries in issues/PRs, but avoid assuming comments/bodies are infinite evidence storage.
• Use internal wording that can map to other forges where practical, without weakening the GitHub-native CLI experience.

Suggested next decomposition

The next useful work is to split this proposal into implementation issues, probably:

1. State-aware ticket resolver hardening
2. Review packet output contract and verdict schema
3. Finish readiness and finish receipt format
4. Workflow drift audit command
5. Workspace status JSON contract
6. Agent/review/finish queue definitions
7. Milestone/work-batch follow-up after [Task] Add first-class milestone lifecycle and bulk ticket assignment #524

#524 already implemented the first-class milestone lifecycle direction, so this proposal should now be updated or followed by child issues that build on top of that completed slice.