# Spec: ADR Session Awareness

## Purpose

Defines the `os-adr` SessionStart behavior: a deterministic, model-free existence check that injects a near-zero-token usage note when a project's ADR system exists, and a suppressible, once-per-day setup suggestion when it doesn't.

## Requirements

### Requirement: Deterministic SessionStart existence check
The plugin SHALL register a SessionStart hook (matcher `startup|resume`) that deterministically
checks for `docs/adr/` and its index file in the current project. The hook SHALL make no LLM
call, SHALL complete within its configured timeout (5s), and SHALL add no perceptible
session-start latency.

#### Scenario: Hook is deterministic
- **WHEN** the SessionStart hook runs
- **THEN** its output is a pure function of the project's filesystem state (ADR dir, index,
  suppression state) with no model invocation

### Requirement: Minimal context injection when the ADR system exists
WHEN `docs/adr/` and the index file both exist, the hook SHALL inject a near-zero-token
additionalContext note stating that the ADR system exists and naming both usage surfaces:
writing (`/os-adr:create`) and retrieval (`/os-adr:find`).

#### Scenario: Present project gets the usage note
- **WHEN** a session starts in a project with `docs/adr/` and an index
- **THEN** the injected context is a short note (a few lines at most) naming `/os-adr:create`
  and `/os-adr:find`

### Requirement: Setup suggestion with suppression when absent
WHEN the ADR system is absent, the hook SHALL notify the user and suggest `/os-adr:init` or
`/os-adr:migrate` — unless a per-project suppression flag is set, in which case it SHALL stay
silent. The suggestion SHALL also be rate-limited to at most once per day per project via a
snooze timestamp. Suppression state SHALL live in a gitignored per-project state directory
(`.os-adr/`), following the `os-doc-hygiene` state-dir shape.

#### Scenario: Absent and unsuppressed
- **WHEN** a session starts in a project with no `docs/adr/` and no suppression flag, and no
  reminder was shown today
- **THEN** the hook emits a one-line suggestion to run `/os-adr:init` or `/os-adr:migrate` and
  stamps the snooze timestamp

#### Scenario: Suppressed project stays silent
- **WHEN** a session starts in a project whose `.os-adr/suppress` flag is set
- **THEN** the hook emits nothing

#### Scenario: Same-day repeat session
- **WHEN** a second session starts the same day in an absent, unsuppressed project
- **THEN** no repeat suggestion is emitted