Review & Provenance

Provenance is the ability to trace any line of code back to the conversation, AI exchange, or manual edit that created it. Stoa tracks provenance automatically across both CLI sessions and web collaboration.

Provenance Map

The provenance map creates bidirectional links between code and conversations:

• Code to Conversation: Click a line in the editor to see which transcript segment or AI exchange created it
• Conversation to Code: Click a transcript exchange to highlight all lines it affected

Color Coding

How It Works

1. Every file change is recorded in the journal with attribution
2. The correlation engine links changes to AI exchanges
3. Provenance marks are stored in the CRDT at the character level
4. The review UI renders these marks as colored highlights

Review Layout

The review page provides a three-panel view for exploring provenance:

Panel 1: File Tree

Navigate between files in the project. Click a file to load it in the editor panel.

Panel 2: Document Editor

The code editor with provenance highlighting:

• Lines are highlighted with colors indicating their origin
• Click any line to see its provenance in the transcript panel
• Supports browser back/forward navigation for file changes

Panel 3: Transcript / Comments

Two tabs:

Transcript:

• Full conversation history from the session
• User prompts and agent responses
• Clickable entries that highlight related code
• Focused exchange highlight shows the active selection
• Smart scroll that only moves to target lines if they aren't already visible

Comments:

• Inline comment blocks extracted from the editor
• Threaded discussion on specific code sections
• Persistent across sessions

Resizable Panels

All three panels are resizable by dragging the dividers. Panels can be collapsed to focus on specific content.

Provenance Dialog

A floating overlay that shows all provenance mappings for the current file:

• Lists all exchanges with their line ranges
• Click any mapping to jump to the specific edit
• Can be shown or hidden as needed

Version History

Explore the full history of any file with provenance context:

# View file history
stoa history src/api.ts

# Interactive browser
stoa history src/api.ts -i

# View file at specific version
stoa show src/api.ts@5

# Compare versions
stoa diff src/api.ts@3@5

Each version entry shows:

• Version number and timestamp
• Description of the change
• Exchange ID (if AI-generated)
• Purpose statement (from enrichment)

What's Next