1# Spec Browser and Diff View23## Purpose45The dashboard plugin SHALL provide a spec browser for current OpenSpec specs and diffs across working tree and git refs. The browser must help maintainers inspect requirements, scenarios, metadata, and changes without reading raw markdown unless they choose to.67## Requirements89### Requirement: Current spec browser mode10The dashboard API SHALL return the current worktree spec set for an initialized source when no diff parameters are requested.1112#### Scenario: List current specs13- **GIVEN** markdown specs exist under `openspec/specs/`14- **WHEN** the dashboard requests the spec browser without before/after refs and without dirty mode15- **THEN** the API returns mode `current`, current branch, each spec path, token, title, status `current`, content, and changed flag `false`1617#### Scenario: Current spec timestamps18- **GIVEN** git history or filesystem metadata is available for a current spec19- **WHEN** the API returns current spec browser entries20- **THEN** each entry includes most-recent edit time when available and creation time when git history can determine it2122### Requirement: Dirty worktree diff mode23The dashboard API SHALL compare a git ref to current worktree specs when dirty mode is requested.2425#### Scenario: Dirty diff defaults26- **WHEN** dirty mode is requested without an explicit before ref27- **THEN** the API compares `HEAD` to the working tree2829#### Scenario: Dirty diff filters unchanged specs30- **GIVEN** some specs match the selected before ref exactly31- **WHEN** dirty mode is requested32- **THEN** unchanged specs are omitted from the returned files list3334#### Scenario: Dirty diff entry35- **GIVEN** a spec was added, modified, or deleted relative to the before ref36- **WHEN** dirty mode is requested37- **THEN** the API returns before content, after content, status, changed flag, unified diff, and available timestamps for that spec3839### Requirement: Ref-to-ref diff mode40The dashboard API SHALL compare specs between two explicit git refs when both before and after refs are supplied.4142#### Scenario: Valid ref comparison43- **GIVEN** both before and after refs are supplied44- **WHEN** the dashboard requests the spec browser45- **THEN** the API returns mode `refs`, both labels, all spec paths present in either ref, per-spec status, before content, after content, changed flag, and unified diff when changed4647#### Scenario: Incomplete ref comparison48- **WHEN** only one of before or after is supplied outside dirty mode49- **THEN** the API rejects the request with a 400-level error explaining that both refs are required5051### Requirement: Safe spec path handling52The API SHALL prevent spec detail and git content reads from escaping `openspec/specs/`.5354#### Scenario: Worktree spec path traversal55- **WHEN** a spec detail request contains an absolute path or parent-directory traversal outside the specs root56- **THEN** the API returns not found and does not read outside the specs directory5758#### Scenario: Ref spec path traversal59- **WHEN** a git-ref spec read is requested for an absolute path or a path containing `..`60- **THEN** the API returns no content and does not invoke git with an escaped specs path6162### Requirement: Spec detail API63The dashboard API SHALL expose the content of a selected current spec.6465#### Scenario: Existing spec detail66- **GIVEN** a requested spec path exists under `openspec/specs/`67- **WHEN** the dashboard requests spec detail68- **THEN** the API returns the path, title, and markdown content6970#### Scenario: Missing spec detail71- **WHEN** the dashboard requests a spec path that does not exist under `openspec/specs/`72- **THEN** the API returns a not-found response7374### Requirement: Structured requirement display75The dashboard UI SHALL render OpenSpec requirements and scenarios as structured content in spec and diff views when the format is recognized.7677#### Scenario: Requirement section parsing78- **GIVEN** spec content contains OpenSpec requirement headings and scenario headings79- **WHEN** the UI renders the spec or diff view80- **THEN** it displays requirement names, requirement text, scenario names, and scenario bullets as structured elements instead of a raw markdown block8182#### Scenario: Unknown markdown fallback83- **GIVEN** spec content does not match the recognized OpenSpec requirement format84- **WHEN** the UI renders the spec or diff view85- **THEN** it falls back to safe markdown rendering rather than hiding content8687### Requirement: Copyable identifiers88The spec browser SHALL expose copyable identifiers for sources, changes, and specs that agents can resolve later.8990#### Scenario: Copy spec token91- **GIVEN** a spec browser entry has a source name and spec token92- **WHEN** the user copies the identifier chip93- **THEN** the copied text is `<source-name>/<os_token>` and can be resolved by `openspec_context`9495#### Scenario: Copy feedback96- **WHEN** a user copies an identifier chip97- **THEN** the UI gives brief visible feedback that the value was copied