| name | edictum-oss |
| description | Implement features in the Edictum OSS core (src/edictum/). Use when the task touches pipeline, adapters, YAML engine, CLI, audit, envelope, or session. Core NEVER imports from ee/. |
Edictum Core Implementation
Read CLAUDE.md first. Understand the boundary principle before writing code.
Scope
Everything under src/edictum/ is the core library (MIT). This includes:
- Pipeline (
pipeline.py) — CheckPipeline, PreDecision, PostDecision
- Envelope (
envelope.py) — ToolCall, Principal, create_envelope()
- Contracts (
rules.py) — @precondition, @postcondition, @session_contract, Decision
- YAML engine (
yaml_engine/) — loader, evaluator, compiler (including sandbox compilation), templates
- Adapters (
adapters/) — all 7 framework adapters
- Audit (
audit.py) — AuditEvent, StdoutAuditSink, FileAuditSink, RedactionPolicy
- Session (
session.py) — Session, MemoryBackend
- CLI (
cli/) — validate, check, diff, replay, test
- Telemetry (
telemetry.py) — OTel spans, GovernanceTelemetry
- Server SDK (
server/) — client components for connecting to edictum-server
Architecture
Two deployment units:
- Core (
pip install edictum) — runs fully standalone. All 4 rule types (pre, post, session, sandbox), pipeline, 7 adapters, CLI, local audit, local approval.
- Server (
edictum-server) — separate deployment, coming soon. The Server SDK (pip install edictum[server]) provides the client-side connectivity.
Core provides protocols and interfaces. The server SDK provides HTTP-backed implementations.
What needs the server
Most features work without the server. These require it:
| Feature | Core | Server |
|---|
| Rule evaluation (all 4 types) | Yes | -- |
outside: block / action: block | Yes | -- |
outside: ask / action: ask (dev) | Yes (LocalApprovalBackend) | -- |
outside: ask / action: ask (production) | -- | Yes (ServerApprovalBackend) |
| Audit to stdout/file/OTel | Yes | -- |
| Centralized audit dashboard | -- | Yes (ServerAuditSink) |
| Session tracking (single process) | Yes (MemoryBackend) | -- |
| Session tracking (multi-process) | -- | Yes (ServerBackend) |
| Hot-reload rules | -- | Yes (ServerRuleSource) |
Workflow
- Read CLAUDE.md — understand boundaries and dropped features
- Read the Linear ticket or user description
- Read relevant source files before proposing changes
- Scenarios & use cases — before implementing, write down:
- What concrete scenarios does this feature enable?
- What user personas benefit?
- Does this overlap with existing features?
- Does this surface related features that should be designed separately?
- Include this analysis in BOTH:
- The PR body under a
## Scenarios section
- The docs page under a
## When to use this section (see .docs-style-guide.md page structure pattern)
- Scope with user — confirm approach before writing code
- Implement — small, focused changes
- Behavior test — every new/changed API parameter gets a test in
tests/test_behavior/test_{module}_behavior.py
- Docs-code sync —
pytest tests/test_docs_sync.py -v
- Adapter parity — if touching adapters:
pytest tests/test_adapter_parity.py -v
- Test —
pytest tests/ -v then ruff check src/ tests/
- Commit — conventional commits, no Co-Authored-By
Conventions
- Frozen dataclasses for immutable data
- All pipeline/session/audit methods are async
from __future__ import annotations in every file- Type hints everywhere
- Test file per module:
tests/test_{module}.py
Do NOT
- Implement Redis/DB StorageBackend — dropped feature
- Accept a parameter without testing its observable effect — if it's accepted, it must DO something testable
- Document a feature that doesn't exist in code —
pytest tests/test_docs_sync.py -v catches this
- Ship an adapter change without running parity checks —
pytest tests/test_adapter_parity.py -v
