Shadow Fragments

Shadow Fragments are the primary mechanism through which AI agents communicate suggestions to humans in VeloGit.

Definition

A Shadow Fragment is a piece of metadata that represents a proposed change to a file. It is “shadowed” because it exists outside of the Git repository’s object store, and it is a “fragment” because it typically represents a specific change rather than an entire file.

Anatomy of a Fragment

Each Shadow Fragment contains several key pieces of information:

• Commit SHA: The specific commit the suggestion is based on.
• File ID: The path of the file to be modified.
• Agent ID: The unique identifier of the AI agent that generated the suggestion.
• Diff Content: A standard unified diff representing the proposed changes.
• Confidence: A numerical value (0.0 to 1.0) indicating the agent’s confidence in the suggestion.
• Status: The current state of the fragment (e.g., pending, melded, rejected).

The Lifecycle of a Fragment

1. Generation: An agent detects a commit event and generates a fragment based on the code analysis.
2. Review: A human views the fragment in the Ghost Workspace. The UI displays the suggestion as an overlay on the original code.
3. Action:
   • Meld: The human accepts the suggestion. VeloGit automatically applies the diff and creates a new human-approved commit.
   • Reject: The human dismisses the suggestion. The fragment is marked as rejected and hidden from the workspace.

Why not use Pull Requests?

While Pull Requests are excellent for long-lived features, they are often too heavyweight for small AI suggestions like “add a missing null check” or “fix a lint error.” Shadow Fragments provide a much faster, lower-friction path for these types of improvements without the overhead of branch management.