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

CLI Provenance Commands

Blame

See which AI exchange authored each line of code:

# Blame an entire file
intent blame src/auth/middleware.ts

# Blame a specific line
intent blame src/auth/middleware.ts 42

# Include file content in output
intent blame src/auth/middleware.ts --content

# JSON output
intent blame src/auth/middleware.ts --json

# Verbose with full exchange details
intent blame src/auth/middleware.ts --verbose

Output includes:

• Line number and content
• Commit SHA (in Git Mode)
• Author name
• Exchange ID
• Agent type
• The user prompt that triggered the change

Trace

See all files modified by a specific AI exchange:

# Trace an exchange
intent trace 1ea90095:0

# JSON output
intent trace 1ea90095:0 --json

# Verbose with full context
intent trace 1ea90095:0 --verbose

Output includes:

• Files modified with line ranges
• Session context
• User prompts
• Timing information

Parse

Generate review artifacts from Git commit provenance:

# Generate markdown summary
intent parse abc123

# Custom output directory
intent parse abc123 --output ./reviews

# JSON format
intent parse abc123 --format json

Produces:

• summary.md (or .json): human-readable review of what changed and why
• annotations.json: machine-readable provenance data

Bookmarks

Save frequently accessed files or AI prompts for quick reference:

File Bookmarks

• Click to open the bookmarked file (works across projects in a Space)
• Shows file name and project context
• Quick access from the Bookmarks section of the left sidebar

Prompt Bookmarks

• Save reusable prompt templates for the AI agent
• Click a prompt bookmark to load it into the agent composer as a draft
• Useful for recurring tasks or standardized prompts

Managing Bookmarks

Bookmarks are accessible from the Bookmarks accordion section in the left sidebar (shortcut: G B).

Version History

Explore the full history of any file with provenance context:

# View file history
intent history src/api.ts

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

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

# Compare versions
intent 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