1# OpenSpec Source Registry23## Purpose45The plugin SHALL maintain a lightweight registry of repositories that the OpenSpec dashboard and agent tools can address by stable, copyable identifiers. The registry is intentionally separate from OpenSpec artifact storage: sources are stored in SQLite, while changes and specs are read live from each repository's filesystem.67## Requirements89### Requirement: Profile-local source storage10The registry SHALL store OpenSpec sources in the active Hermes home so each Hermes profile has an independent source list.1112#### Scenario: Registry database path13- **WHEN** the registry opens its database14- **THEN** it uses `<hermes_home>/openspec.db` from Hermes' profile-aware home resolver1516#### Scenario: Database initialization17- **WHEN** source data is first read or written18- **THEN** the registry creates the source table and unique path index if they do not already exist1920### Requirement: Source record identity21Each registered source SHALL have a stable internal token, an optional vanity name, an absolute or user-expanded path string, and a creation timestamp.2223#### Scenario: Add new source24- **GIVEN** a path is not already registered25- **WHEN** the registry adds the source26- **THEN** it generates an `os_` token, stores the source, and returns token/id aliases, name, path, and created_at2728#### Scenario: Duplicate source path29- **GIVEN** a source path is already registered30- **WHEN** the registry attempts to add the same normalized path again31- **THEN** it rejects the operation with a duplicate-source error3233#### Scenario: Update source34- **GIVEN** an existing source token35- **WHEN** the registry updates the source path or vanity name36- **THEN** it preserves the token and creation timestamp while replacing the path and name3738#### Scenario: Remove source39- **GIVEN** an existing source token40- **WHEN** the registry removes the source41- **THEN** the source no longer appears in registry listings or identifier resolution4243### Requirement: Human-facing source names44The registry SHALL resolve sources by explicit vanity name first and by path basename when no vanity name is set.4546#### Scenario: Explicit vanity name47- **GIVEN** a source has a non-empty `name`48- **WHEN** an agent resolves that name case-insensitively49- **THEN** the registry returns the matching source5051#### Scenario: Basename fallback52- **GIVEN** a source has no explicit `name`53- **WHEN** an agent resolves the basename of the source path case-insensitively54- **THEN** the registry returns the matching source5556### Requirement: Deterministic artifact tokens57The registry SHALL derive copyable `os_` artifact tokens deterministically from change names and spec paths rather than storing per-artifact rows.5859#### Scenario: Change token derivation60- **WHEN** a change folder name is converted into a token61- **THEN** the token is a stable `os_` value derived from the change name6263#### Scenario: Spec token derivation64- **WHEN** a spec path is converted into a token65- **THEN** the token is a stable `os_` value derived from the `spec:<relative-path>` key6667#### Scenario: Filesystem stays authoritative68- **GIVEN** a change or spec is renamed, added, archived, or removed on disk69- **WHEN** tools scan the repository70- **THEN** the current filesystem state determines which artifact tokens resolve7172### Requirement: Legacy source migration73The registry SHALL support one-time migration from legacy dashboard configuration sources into the SQLite registry.7475#### Scenario: Legacy sources exist76- **GIVEN** the Hermes dashboard config contains legacy OpenSpec source entries77- **WHEN** the plugin API lists registered sources for the first time in a process78- **THEN** it attempts to migrate those sources into the registry idempotently7980#### Scenario: Legacy migration failure81- **WHEN** legacy source migration raises an exception82- **THEN** source listing continues using the SQLite registry without crashing the dashboard API