Architecture Decision Records
The decisions that shaped skep, in order. Each ADR records the question it answered (the Q/G/D codes trace back to the original design review) and the version that landed it.
New ADRs and plans start from the invariants — the traits no change may trade away (Part I, with the review checklist) and the refinement backlog (Part II). Cite the invariant numbers a decision touches.
| ADR | Decision |
|---|---|
| 0001 | The contract owns itself (Q2-A) |
| 0002 | Worktree + patch artifact; applying the patch is the approval (Q5-A) |
| 0003 | Store carve-out boundary (Q6-A) |
| 0004 | Licensing (G1) |
| 0005 | Worker runs inside a macOS Seatbelt sandbox (Q1-A, v2) |
| 0006 | Supervisor-side re-verification (G10, v2) |
| 0007 | Auto-approval policy rules (D3, v2) |
| 0008 | True suspend/resume of pending_approval (Q8, v2) |
| 0009 | Usage accounting (G8, v2) |
| 0010 | Storage gate: SQLite-WAL single writer (G4, v3) |
| 0011 | Network domain-allowlist enforcement via a loopback proxy (D1, v3) |
| 0012 | Recurring schedules: cron drives a stateless tick (v3) |
| 0013 | D3 auto-approval goes active; the U1 acceptance demo (v3) |
| 0014 | Containerized worker isolation for Linux portability (Q1-B/G3, v3) |
| 0015 | Workflow templates: a filled template is just a normal task (v3.5) |
| 0016 | Learned skills: a generated template, gated into the same registry (v4) |
| 0017 | skep serve: the API daemon, the ticker, and mutable config (v5) |
| 0018 | The box: container packaging and the Linux sandbox posture (v5) |
| 0019 | LLM chat in the Queen: the voice, and the gated hands (v6) |
| 0020 | Notes & Tasks gating line (v7 Stage B) |
| 0021 | Interactive browser automation: deferred, with named triggers (v37-F5) |
| 0022 | Policy-first: one schema, two vocabularies, govern-via-MCP (v40, executing v36) |
| 0023 | Queen-side file reads as a policy-governed tool surface (v51-F2) |
| 0024 | Inline code execution as a governed script worker (v51-F3) |
| 0025 | Batch dispatch as N independent governed runs (v51-F5) |
| 0026 | Operator-policy resolution: the Queen's standing policy (v52) |
| 0027 | Chat context injection: memory and the skill index (v53-F2/F7) |
| 0028 | Profile-level persona: persona.md (v53-F4) |
| 0029 | Conversation-authored skills: observer + curator (v53-F1) |
| 0030 | Cron context chaining (v53-F5) |
| 0031 | Voice as a channel-layer capability (v53-F6) |
| 0032 | Card auto-deny on timeout (v54-F1) |
| 0033 | Human-readable confirmation cards (v54-F3) |
| 0034 | Multi-run PR grouping (v54-F4) |
| 0035 | Repo freshness is managed by the supervisor (v55-F1/F2) |
| 0036 | Per-project policy copy (v55-F4) |
| 0037 | Chat context: explicit window, budgeted replay, compaction (v56-F1/F2/F3) |
| 0038 | Approvals announce themselves (v56-F5/F6/F7) |
| 0039 | The Queen's git surface: reads free, mutations carded (v57) |
| 0040 | Bounded reactive worker execution — the act–observe loop (R2, v69) |
| 0041 | Reasoning-only delegation: delegate_analysis, cap 3 (v83-F7) |
| 0042 | Prompt schedules: read-only, store-reads-only Queen turns (v83-F5) |
| 0043 | Seed skills and the zero-grant rule (v83-F12/F13) |
| 0044 | Outbound content: verbatim cards, never-grantable prefixes (v84-F4) |
| 0045 | External shelves and the skill-pack ladder (v85) |
| 0046 | Session approval tier for the worker shell gate (v86) |
| 0047 | CLI-agent engines and where their authority boundary is (v90) |
| 0048 | Policy groups: reusable convenience grants, live-composed (v97) |
| 0049 | The caste roster is a registry, not five dict literals (v101) |
| 0050 | One verb, three faces: the operator's surface is never the narrow half (v104) |
| 0051 | The provider shelf: presets, per-profile keys, no borrowed identity (v108) |
| 0059 | Policy v3: one decide(), layer-aware ceilings, scoped grants (edge sweep; P3-1 implemented) |
| 0060 | Serve re-adopts a live worker after a restart (edge sweep D2) |
| 0061 | Unlocked mode on policy v3: a zero-ask project as one step inside decide() |
| 0062 | The provider-key relay: the worker never holds the provider key (V6b; behind a kill switch, default off) |
| 0063 | The Queen on a ChatGPT plan: the Codex login as a provider credential, Queen only (v118) |
| 0066 | New projects run sandboxed when the host can sandbox; stored modes are carried forward (v127-F8) |
| 0067 | A channel admin named at the desk confirms every card from the messenger, HIGH ones included (v130-F5) |