Git repository status and diff BFF API

[oscharko]

Parent Epic: #1491

Purpose

Provide safe, read-first Git integration for repository status, branch, changes, staged state, and diffs through the local BFF.

Feature Categories

• UI/UX
• Workflow
• Backend / API
• Documentation
• Infrastructure / DevEx
• Security / Privacy
• Performance
• Accessibility
• Other: not applicable

Epic And Board Placement

• Parent Epic: #1491 is present and points to the governing open epic.
• This issue is linked as a GitHub sub-issue of the parent epic, not only referenced in Markdown.
• This issue appears under the parent epic swimlane on the public Keiko Product Delivery board.
• Project fields are set before handoff: Classification: Task, Status: Open Issues, Workflow State: New or Triaged, inherited or explicit Priority, and Human Review Required: Yes.
• The parent epic remains Classification: Epic, Status: Open Epics, and positioned in the board's top-to-bottom implementation order.
• Card Chat or conversation-card work uses this same parent/sub-issue and board placement flow; do not create loose chat/card issues outside an epic swimlane.

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: implementor | security-reviewer | test-engineer | verifier.
• Primary area label: area:git.
• Expected write ownership: Git BFF module/routes/contracts, editor/UI status integration, and tests.

Existing Capability Review

• Existing Keiko packages, UI surfaces, server routes, contracts, validation helpers, evidence models, memory/local-knowledge graph patterns, workflow state, and tool/workspace boundaries were inspected before implementation.
• The issue identifies what will be reused, extended, generalized, or left untouched.
• Any new implementation is justified as a real capability gap, not a parallel implementation of existing behavior.
• Refactoring or consolidation was considered when existing functionality is close but not yet shaped for this issue.

Required review targets:

• Existing workspace-root containment.
• Runtime capability detector.
• Any current Git usage in scripts or UI.
• Git safe.directory behavior and repository ownership handling.

Delivery Board Workflow

• Add this issue to the public Keiko Product Delivery project before work starts.
• Set project Classification to Task.
• Set project Status to Open Issues while the issue is open and unclaimed.
• Confirm this issue is visible under the parent epic swimlane through the GitHub sub-issue relationship.
• 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.
• Reuse/extension/generalization evidence or gap rationale is documented in the issue or linked PR.
• Studio browser quality gate when Studio UI or BFF browser behavior changes.
• Studio performance and memory gates when editor performance, Monaco, rendering, or large-output behavior changes.
• Studio visual regression when visible UI structure changes.
• Markdown link check when documentation changes.
• W0.2 release gate when W0.2 product-path semantics change.
• W0.3 release gate when W0.3 workflow or Studio hardening semantics change.
• Security review when trust boundaries, auth/session, secrets, CSP, model access, execution, patch application, or external calls change.
• Qodana/static-analysis review when security-sensitive or shared control-plane code changes.
• Server tests for clean, dirty, staged, untracked, branch, detached HEAD, non-repo, and unsafe repo states.
• Security tests for path traversal and repository ownership errors.
• Browser test for status display and diff viewing.
• Output cap tests for large diffs.

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 existing Keiko functionality can satisfy the issue outcome through reuse, extension, or generalization; update the issue or PR with the reuse plan instead of implementing a duplicate subsystem.
• 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

Implement read-focused Git APIs for repository discovery, branch, status porcelain, staged/unstaged changes, file diffs, and bounded output. Use native Git or a documented library decision after review.

Out of Scope

• Commit/push UI unless explicitly added in a later child issue.
• Running Git hooks.
• Credential management.
• Remote provider integration.

Deliverables

• Git status/diff contracts.
• BFF API routes.
• Bounded diff output and error envelopes.
• UI integration for status and changed-file indicators where scoped.

Acceptance Criteria

• Non-Git folders show a clean unavailable state.
• Unsafe repository ownership is surfaced without bypassing Git protections.
• Diff output is bounded and redacted where required.
• No browser code invokes Git directly.

Engineering Notes

Git official docs distinguish porcelain and plumbing commands. Prefer stable machine-readable output such as porcelain status where native Git is used.

Grounding References

• Language Server Protocol 3.18 specification: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/
• VS Code language extension architecture: https://code.visualstudio.com/api/language-extensions/overview
• VS Code language server extension guide: https://code.visualstudio.com/api/language-extensions/language-server-extension-guide
• Monaco Editor documentation: https://microsoft.github.io/monaco-editor/
• CodeMirror 6 reference and lint model: https://codemirror.net/docs/ref/ and https://codemirror.net/examples/lint/
• Eclipse JDT Language Server: https://github.com/eclipse-jdtls/eclipse.jdt.ls
• Pyright: https://microsoft.github.io/pyright/
• Docker rootless mode: https://docs.docker.com/engine/security/rootless/
• NIST SP 800-190 Application Container Security Guide: https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-190.pdf
• Git safe.directory and protected configuration: https://git-scm.com/docs/git-config
• Git plumbing and porcelain model: https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain
• SWE-bench paper: https://arxiv.org/abs/2310.06770
• OpenHands paper: https://arxiv.org/abs/2407.16741
• Survey on code generation with LLM-based agents: https://arxiv.org/abs/2508.00083