edictum-oss
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/.
SKILL.md.claude/skills/edictum-oss/SKILL.md
GitHubEdictum 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
## Scenariossection - The docs page under a
## When to use thissection (see.docs-style-guide.mdpage structure pattern)
- The PR body under a
- 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/ -vthenruff 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 annotationsin 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 -vcatches this - Ship an adapter change without running parity checks —
pytest tests/test_adapter_parity.py -v