specs/008-commit-browser/spec.md

Ref: main   Size: 6.9 KiB

# Feature Specification: Commit Browser in TUI Dashboard

**Feature Branch**: `008-commit-browser`
**Created**: 2026-03-21
**Status**: Draft
**Input**: User description: "Add the ability to browse commit details from within the dashboard. When viewing a patch or issue, show the event commit history and allow inspecting individual commits (author, timestamp, event type, signature status). Currently you can checkout with 'o' but there's no in-dashboard commit exploration."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - View Event History for an Item (Priority: P1)

A user viewing a patch or issue in the dashboard wants to see the full event history — all the commits that make up the collaboration DAG for that item. They press a key to open a commit/event list showing each event's type (e.g., IssueOpen, PatchReview, PatchComment), author, and timestamp in chronological order.

**Why this priority**: Without seeing the event history, there is no commit browsing at all — this is the core of the feature.

**Independent Test**: Select an issue or patch with multiple events, press the commit browser key, and verify a scrollable list of events appears with type, author, and timestamp for each.

**Acceptance Scenarios**:

1. **Given** the user is viewing an issue or patch in the detail pane, **When** they press the commit browser key, **Then** a list of all events for that item appears showing event type, author name, and timestamp for each entry.
2. **Given** the event list is displayed, **When** the user scrolls up and down, **Then** the list navigates through events correctly.
3. **Given** the event list is displayed, **When** the user presses Escape, **Then** the view returns to the normal detail view.
4. **Given** an issue or patch has only one event (e.g., just the opening event), **When** the user opens the commit browser, **Then** a single entry is shown.

---

### User Story 2 - Inspect Individual Event Details (Priority: P2)

After opening the event list, the user selects a specific event to see its full details: the commit ID, author name and email, timestamp, event type, and the payload contents (e.g., for a comment event, the comment body; for a review, the verdict and body).

**Why this priority**: Seeing the list is useful on its own, but inspecting details completes the browsing experience.

**Independent Test**: Open the event list, select an event, and verify the detail view shows commit ID, author, timestamp, event type, and payload.

**Acceptance Scenarios**:

1. **Given** the event list is displayed, **When** the user selects an event and presses Enter, **Then** the detail view shows the commit ID (short hash), author name and email, timestamp, event type, and event-specific content.
2. **Given** the user is viewing event details, **When** they press Escape, **Then** they return to the event list.
3. **Given** the event is a comment, **When** viewing details, **Then** the comment body is displayed.
4. **Given** the event is a review, **When** viewing details, **Then** the verdict and body are displayed.

---

### User Story 3 - View Signature Status (Priority: P3)

The user wants to know whether each event commit was signed and whether the signature is valid, invalid, missing, or from an untrusted key. This information is shown alongside each event in the list and in the detail view.

**Why this priority**: Signature verification adds trust information but the feature is fully usable without it.

**Independent Test**: Open the event list for an item with signed events and verify signature status indicators appear next to each event.

**Acceptance Scenarios**:

1. **Given** the event list is displayed, **When** an event commit has a valid signature, **Then** a "valid" indicator is shown next to that event.
2. **Given** the event list is displayed, **When** an event commit has no signature, **Then** a "missing" indicator is shown.
3. **Given** the event list is displayed, **When** an event commit has an invalid or untrusted signature, **Then** the appropriate indicator is shown.
4. **Given** the user is viewing event details for a signed event, **When** they look at signature information, **Then** the public key and verification status are displayed.

---

### Edge Cases

- What happens when the user presses the commit browser key with no item selected? Nothing happens — the key is ignored.
- What happens when the DAG ref cannot be read (e.g., corrupted ref)? An error message appears in the status bar and the commit browser is not opened.
- What happens when the event list is very long (hundreds of events)? The list is scrollable and renders efficiently without freezing.
- What happens when the user presses the commit browser key while in search mode or issue creation mode? The keypress is captured by the active input mode, not treated as a commit browser trigger.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: System MUST provide a commit browser mode activated by a designated key from the detail pane of any issue or patch.
- **FR-002**: System MUST display a scrollable list of all events for the selected item, ordered chronologically.
- **FR-003**: Each event in the list MUST show the event type, author name, and timestamp.
- **FR-004**: System MUST allow the user to select an event and view its full details including commit ID, author name and email, timestamp, event type, and event payload content.
- **FR-005**: System MUST allow the user to dismiss the commit browser and return to the normal view using Escape.
- **FR-006**: System MUST display signature verification status for each event when signature data is available.
- **FR-007**: System MUST handle errors gracefully when reading event data, showing an error message in the status bar.
- **FR-008**: System MUST support keyboard navigation (up/down arrows) through the event list.

### Key Entities

- **Event Entry**: A single event in the collaboration DAG, containing commit ID, timestamp, author, event type/action, and optional signature information.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Users can view the full event history of any issue or patch without leaving the TUI dashboard.
- **SC-002**: Users can inspect individual event details (commit ID, author, timestamp, type, payload) with no more than 2 keypresses from the detail view.
- **SC-003**: Navigation through the event list is responsive with no perceptible delay for items with up to 100 events.
- **SC-004**: All existing keyboard shortcuts continue to function when the commit browser is not active (no regressions).

## Assumptions

- The commit browser key is not currently bound to any action in the TUI detail pane and is available.
- Event data is read from the existing DAG walking functions — no new data sources are needed.
- The commit browser replaces or overlays the current detail pane content; it does not open a new window or pane.
- Signature verification uses the existing verification infrastructure.