# Spec: ADR Retrieval

## Purpose

Defines how relevant ADRs are found by the `os-adr` plugin: deterministic-first layered narrowing (frontmatter match, status filter, Graphify expansion) with AI judgment applied only to the narrowed candidate set, graceful degradation without a project graph, a mid-task-callable query surface, and eval-readiness sketches accompanying the build.

## Requirements

### Requirement: Deterministic-first retrieval layering
ADR retrieval SHALL narrow candidates through ordered layers: (1) path/component match of query
inputs against each ADR's `affected-paths`/`affected-components` frontmatter; (2) status filter
admitting only `Accepted` ADRs by default, with an explicit override to include other statuses;
(3) Graphify graph traversal when a project graph exists; (4) AI judgment applied only to the
already-narrowed candidate set. AI judgment SHALL never be applied to the full ADR corpus.

#### Scenario: Path match narrows first
- **WHEN** retrieval is queried with file paths being edited
- **THEN** ADRs whose `affected-paths` match are selected before any model involvement

#### Scenario: Default status filter
- **WHEN** retrieval runs without an override
- **THEN** only `Accepted` ADRs appear in the candidate set

#### Scenario: AI sees only the narrowed set
- **WHEN** the AI-judgment layer runs
- **THEN** it receives only the candidates surviving layers 1–3, not the full corpus

### Requirement: Graph layer degrades gracefully
WHEN no `graphify-out/` project graph exists (or ADRs are not yet indexed as graph nodes),
retrieval SHALL still function using layers 1, 2, and 4, without error.

#### Scenario: No project graph present
- **WHEN** retrieval runs in a project that has never been onboarded to Graphify
- **THEN** results are produced from frontmatter matching and status filtering alone

### Requirement: Mid-task-callable query surface
Retrieval SHALL be exposed as a `find` skill (`/os-adr:find`) backed by a deterministic CLI,
callable at any point during a task — not only at SessionStart — so an agent can check
in-progress work against existing decisions.

#### Scenario: Query during a task
- **WHEN** an agent mid-task invokes `/os-adr:find` with the files or topic it is working on
- **THEN** it receives the relevant Accepted ADR candidates for those inputs

### Requirement: Eval-readiness sketches accompany the build
Held-out evaluation scenario shapes (write-trigger and retrieval) SHALL be sketched in a design
doc before the plugin skeleton is finalized, and any plugin surface those sketches require SHALL
be part of the initial build. The evaluation itself SHALL NOT be part of this change.

#### Scenario: Sketches exist before skeleton freeze
- **WHEN** the plugin skeleton is finalized
- **THEN** a scenario-sketch document exists covering at least one write-trigger and one
  retrieval scenario shape