# KeiSeiKit Architectural Decisions

> ADR-style log. Each entry: context → decision → consequences. New entries
> at the top. Cross-link from `_primitives/_rust/<crate>/README.md` when a
> decision is crate-local.

---

## 2026-05-25 — Opt-in hook packs + stack profiles (public-prep posture)

### Context

The kit force-activated every hook via `settings-snippet.json`, including the
author's personal research discipline (numeric-claims evidence markers,
no-downgrade, citation-verify, rust-first / no-python). For a public,
general-audience kit that is presumptuous — users bring their own stack and do
not need a Rust-only policy or evidence-marker enforcement by default.

### Decision

- Posture: **safety hooks on by default; all discipline packs opt-in.** Packs:
  `safety` (always), `evidence`, `observability`, `epistemic`, `orchestration`,
  `git-guard`, `stack-rust`. SSoT = `_primitives/hook-packs.toml`.
- **Stack profiles** (minimal / web / ml / systems / mobile) pull a set of
  discipline packs AND an agent set. `rust-first` / `no-python` live only in
  `stack-rust`, which only the `systems` stack enables. `git-guard`
  (no-github-push) is opt-in only and pulled by NO stack — a general kit must
  not block a user's normal `git push` to github.
- Mechanism: install-time **filter** of the snippet by selected packs
  (`filter_snippet_by_packs`) + **prune** of kit-owned hooks on reconfigure
  (`prune_kit_hooks`, foreign hooks preserved). Selection persists to
  `~/.claude/config/onboarding.toml`; re-runnable via `kei configure`.
- Non-interactive / `--yes` / CI default = minimal (safety + cosmetic only),
  all agents (back-compat for power users).

### Consequences

- Gate wiring (`_lib/gate.sh`) added to the 8 highest-friction discipline hooks
  for runtime toggling via the `hooks-control` skill; remaining cosmetic/event
  hooks deferred (install-time filtering already gives "off by default", so the
  runtime gate is a convenience, not a correctness requirement).
- Agent-set changes via `kei configure` apply on the next `./install.sh`
  (reconfigure re-applies hooks fully but does not remove already-installed
  agent manifests — they are harmless extra `.md` files).
- `_toml_array` extracted from `lib-profile.sh:profile_members` as the shared
  one-line-array TOML reader (no new dependency).

## 2026-04-28 — Three scheduling abstractions in workspace

### Context

After Hermes import (P4.2 `kei-cron-scheduler`) the KeiSeiKit workspace
contains **three** scheduler-like primitives. A naive audit reads this as
duplication; in practice each occupies a distinct layer of the stack and
removing any one would break a downstream consumer. This ADR documents the
boundary so a future reader does not consolidate them by mistake.

### The three primitives

| Crate | Storage | Concurrency | Owns runner? | Canonical use |
|---|---|---|---|---|
| `kei-scheduler` | `rusqlite` (sync, metadata-only) | sync | **no** | per-call queryable schedule index |
| `kei-cron-scheduler` | JSON-on-disk + `fcntl` advisory lock | `tokio` async | **yes** | Hermes parity (`/schedule` parser + cron loop) |
| `kei-pipe` cron triggers | embedded in pipe TOML | driven by pipe runtime | depends on pipe | pipeline-level cron embedded in a pipe definition |

### Decision

**Keep all three. Do not consolidate.** Each abstraction encodes a
different ownership contract and a different blast radius on failure.

### Rationale, primitive by primitive

#### `kei-scheduler` — synchronous metadata-only store

Synchronous `rusqlite` schedule store. Stores cron expression, next-run
timestamp, owner, payload pointer. Does **not** dispatch — the caller asks
"what should I run between t and t+Δ" and the caller is responsible for
execution.

This separation matters because two callers want exactly that contract:

- `kei-pipe` queries the schedule from the pipe-runtime loop (already its
  own scheduler) — it must not have a competing async runner inside the
  store.
- `cron-wrapper-agent` test harness wants deterministic, blocking lookups
  with no background tasks. A `tokio` runtime would fight the harness.

A SQLite-backed metadata store is the smallest abstraction that satisfies
both callers. Any `tokio` infrastructure inside this crate would force its
contract on the harness and break determinism.

#### `kei-cron-scheduler` — async runner for Hermes parity

Async `tokio`-based runner. JSON-on-disk persistence (one file per job),
`fcntl` advisory lock to keep multiple binaries from racing the same job
file, owns its own loop, supports interval + standard 5-field cron. This
is the surface imported from Hermes (HERMES-MIGRATION-PLAN P4.2) — the
contract is "set-and-forget recurring scheduler with the runner inside the
crate."

A SQLite-only store like `kei-scheduler` cannot satisfy this contract:

- File-per-job is the unit of `fcntl` locking; a single SQLite file would
  serialise all locks through the SQLite write mutex.
- The runner is part of the public surface — Hermes callers expect to
  hand the crate a job and walk away. Splitting the runner into a
  separate crate would re-litigate the contract on every consumer.

#### `kei-pipe` cron triggers — pipeline-level cron embedded in a pipe

Pipes (KeiSei pipeline definitions, TOML) can declare a cron trigger
inline. The pipe runtime evaluates the trigger as part of the pipe's own
state machine, alongside event triggers, file-watch triggers, and HTTP
triggers. The cron trigger is **not** a separate scheduler — it is a
trigger source within the pipe runtime, which is itself the scheduler.

Re-implementing this on top of `kei-cron-scheduler` would either (a)
duplicate the pipe runtime's lifecycle into the cron crate, or (b) split
a single pipe's triggers across two runtimes, which loses the atomic
"trigger-fired-and-pipe-started" guarantee the pipe runtime provides.

### Consequences

- **Choosing the right primitive for a new caller.** Decision tree:
  - Need a recurring background runner with `fcntl` durability and
    minimal blast radius if a single binary crashes? → `kei-cron-scheduler`.
  - Need a queryable index of "what should I run", with execution owned
    elsewhere? → `kei-scheduler`.
  - Trigger is one of many in a pipe definition, lives next to the data
    flow, dies with the pipe? → `kei-pipe` cron trigger.
- **Fail-loud overlap.** If you find yourself porting a feature from one
  to another (e.g. "let `kei-scheduler` also dispatch"), STOP — that is
  the No-Patching/No-Overlay smell from the umbrella rules. Add the
  feature to the right primitive instead, or write a new one.
- **Audit signal.** A future audit may flag "three schedulers" as a code
  smell. This ADR is the canonical answer; link here from any review
  comment that surfaces the question again.

### References

- `_primitives/_rust/kei-scheduler/`
- `_primitives/_rust/kei-cron-scheduler/`
- `_primitives/_rust/kei-pipe/` (cron trigger source)
- `HERMES-MIGRATION-PLAN.md` §P4.2 — Hermes parity import