Ship typed local branch, staging, and commit flows with commit-intent composition

[oscharko]

Parent Epic: #470

Purpose

Deliver the first end-user-visible governed Git write flows by enabling local branch management, staging, and commit creation through typed tools and approval-aware workflows. This issue turns the abstract mutation platform into a practical delivery capability that users can use daily without leaving Keiko for routine local repository preparation.

The outcome must make local Git writing disciplined rather than magical: users should be able to create or switch branches, assemble staged changes intentionally, preview commit structure, and create high-quality commits that reflect real change intent and repository policy.

Agent Execution Mode

• Single-agent
• Agent team
• Audit-only
• Refactor-only
• Feature delivery
• Audit/verification-heavy
• Human-led / agent-assisted

Agent Routing Hints

• Lead agent: developer.
• Suggested specialist agents: ui-engineer | architect | verifier | pr-reviewer.
• Primary area label: area:desktop-ui.
• Expected write ownership: local Git tools, commit-intent composition logic, server handlers, desktop workflow surfaces, and related tests.

Delivery Board Workflow

• Add this issue to the public Keiko Product Delivery project before work starts.
• Set project Status to Open Issues while the issue is open and unclaimed.
• Keep Workflow State current: New, Triaged, In Progress, PR Open, Ready for Human Review, Blocked, Waiting for User, or Done.
• When an agent starts work, set the issue label to status: in progress, set project Status and Workflow State to In Progress, and fill Owner / Agent.
• When implementation starts, fill the Branch field with the active branch name.
• When a PR is opened, set Workflow State to PR Open, fill Pull Request, and keep Human Review Required set to Yes.
• When the PR is ready for maintainer review, set Workflow State to Ready for Human Review and replace the issue label with status: ready for human review.
• Do not mark Done until the PR is merged, closure evidence exists, the issue is closed, and project Status is set to Done.

Expected Verification

• Required GitHub check: ci.
• Studio browser quality gate when branch, staging, or commit workflow UI changes.
• Studio visual regression when commit workflow surfaces change visible structure.
• Security review when local mutation authority or commit-policy enforcement changes.

Review Settlement and Formal Issue Completion

• The implementation PR waits for required GitHub checks before merge.
• All actionable review findings are fixed or explicitly dispositioned in the PR before merge.
• Acceptance Criteria and Expected Verification checkboxes are updated only when evidence exists.
• Delivery board fields are updated before handoff, including Owner / Agent, Branch, Pull Request, and Human Review Required.
• Required documentation, PR evidence, issue comments, migration notes, screenshots, logs, or follow-up issues are completed when requested by this issue.
• The issue remains open until implementation is merged, review findings are settled, and closure evidence is recorded.

Stop Conditions

• Stop if the implementation would expand beyond this issue's stated scope.
• Stop if required acceptance criteria are missing, contradictory, or no longer match the linked epic.
• Stop if the work requires secrets, customer data, private runtime logs, or token-bearing artifacts.
• Stop if two parallel agents would need to edit the same file scope.
• Stop if the change would weaken architecture boundaries, quality gates, security posture, evidence semantics, deterministic verification, or required ci guarantees.
• Stop after three CI or review-finding repair attempts with different root causes and report the blocker.

Language and Professional Standard

• All issue work, PR descriptions, code comments, configuration properties, schema fields, README updates, Markdown files, and GitHub comments must be written in professional English.
• Use accurate enterprise product terminology; when limitations exist, state them precisely without prototype-only, placeholder, fake, or informal framing.
• Build production-ready, state-of-the-art solutions while keeping implementation simple, maintainable, and focused on the issue scope.
• Be creative and innovative where it improves product quality, but avoid unnecessary special cases, speculative abstractions, and process overhead.

Scope

Ship governed local write flows before any remote publish capability.

In scope:

• Support governed branch creation and branch switching with explicit policy checks and preview semantics.
• Support staging and unstaging workflows that let users intentionally assemble the exact changeset for a commit.
• Add commit-intent composition that can summarize changed scope, suggest semantic commit titles and bodies, and warn about suspicious mixed-scope or WIP-style commits.
• Enforce commit-message policy hooks such as Conventional Commit, DCO, issue key, or similar repo-level rules when configured.
• Link commit preview state to existing verification context where available so users can see relevant tests, checks, or known risk before creating the commit.
• Record evidence and approval state for local branch and commit actions through the shared governed mutation flow.

Out of Scope

• No push, remote publish, PR, or merge execution.
• No fully generalized hunk editor if path-level staging is sufficient for the initial governed flow.
• No unrelated repository browsing redesign.

Deliverables

• Governed branch create or switch flows.
• Staging and unstaging workflow integrated with commit preview.
• Commit-intent composition with policy-aware validation.
• Tests and evidence proving commit creation only occurs through previewed, governed flows.

Acceptance Criteria

• Users can create or switch to a branch, assemble staged changes, preview a commit, and create the commit without leaving the governed workflow.
• Commit creation is blocked when configured message policies or other required local checks fail, and the failure reason is understandable.
• Mixed-scope or low-quality commit drafts are detected or warned on strongly enough to improve commit hygiene rather than silently passing through.
• Evidence and approval semantics are captured for local branch and commit mutations just as they are for later remote actions.
• Browser and integration tests prove that commit creation cannot bypass preview or policy evaluation.

Engineering Notes

This issue should favor intentional commit quality over raw speed. If users can create fast but sloppy commits that later cause remote review friction, the governed local flow is not doing enough work.