50 lines
2.5 KiB
Markdown
50 lines
2.5 KiB
Markdown
|
# 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
|