# os-adr

ADR (architecture decision record) system for cc-os and pilot projects: numbered
`docs/adr/` files + generated index, migration of legacy decision logs, deterministic
find/create/init workflows. Full design/build history: `docs/implementation-status/os-adr.md`.

## Component map

- `skills/` — four verbs, each `/os-adr:<verb>`: `create`, `find`, `init`, `migrate`.
- `lib/adr.rb` + `lib/adr/{detector,finder,index,migration_report,migrator,record,
  repository,template}.rb` — single `Adr` namespace, `require_relative` loading,
  stdlib-only (no external gems).
- `bin/` — **per-verb scripts** (`adr-new`, `adr-find`, `adr-init`, `adr-migrate`,
  `adr-detect`), invoked as `ruby ${CLAUDE_PLUGIN_ROOT}/bin/adr-<verb>` from skills.
  This is **not** the single-dispatcher pattern ADR-0025 requires of newer plugins —
  os-adr is explicitly grandfathered (see below).
- `templates/adr.md` — the ADR template migration and creation write against.
- `hooks/hooks.json` — SessionStart entry is intentionally empty; the check itself
  moved to os-status's `adr-system-present` (`hooks/session_start.py` here is kept
  only as the wording source of record).
- `tests/` — minitest, `ruby tests/all.rb` (glob-runs `*_test.rb`) + `test_helper.rb`
  tmpdir fixtures; `hook_test.py` covers the hooks-parity case.
- `invariants.md` — reversion-protection contract; read before touching detection,
  migration, indexing, or find-filtering logic.
- `eval/`, `eval-b/`, `eval-c/` — Eval A/B/C harnesses (prompted grid, held-out
  unprompted-behavior, ambiguity-ladder). See `docs/implementation-status/os-adr.md`
  for what each measures; eval discipline (reserves never read informally) per root
  `CLAUDE.md`.

## ADR-0025 exemption

The per-verb `bin/` layout (rather than a single `bin/os-adr` dispatcher) is
**grandfathered by
[ADR-0025](../../docs/adr/0025-standard-ruby-structure-for-cc-os-plugins-lib-single-dispatcher-bin-fail-soft-installed-gem-only-dependencies.md)**:
the exemption is recorded there explicitly ("not worth a retrofit until os-adr is
next touched for other reasons"), not an oversight. Don't "fix" the dispatcher shape
as a drive-by — fold it into whatever unrelated work next touches os-adr's `bin/`.

## Pointers

- Decisions: `docs/adr/0025-...md` (Ruby structure), `docs/adr/0020` and its
  amendment (cc-os retrofit).
- Status/build history: `docs/implementation-status/os-adr.md`.