---
aliases:
- Specs Readme
- Specs Navigation
- Zeph Specifications Index
tags:
- sdd
- index
- reference
created: 2026-04-08
status: permanent
related:
- "[[MOC-specs]]"
- "[[constitution]]"
---
# Zeph Specs
Feature principle documents — key invariants for coding agents.
See `[[constitution]]` for project-wide non-negotiable rules.
**See `[[MOC-specs]]` for the comprehensive index of all specifications organized by topic.**
---
## Numbering Scheme
Spec IDs (001–044) follow a logical grouping:
- **001–010**: Foundational contracts and core systems (invariants, loop, providers, memory, skills, tools, channels, mcp, orchestration, security)
- **011–020**: User-facing features and operational integration (TUI, graph memory, protocols, self-learning, filtering, indexing, scheduler, gateway, config loading)
- **021**: `zeph-context` crate — context budget, compaction state machine, context assembler
- **022–034**: Architectural extensions and specialized features (provider registry, complexity routing, multi-model design, classifiers, TUI enhancements, hooks, database abstraction, handoff, feature flags, subagent context, benchmark harness)
- **035–037**: Observability and configuration (profiling/tracing instrumentation, Prometheus metrics export, config schema)
- **038–041**: Infrastructure and security (vault, background task supervisor, content sanitizer, experiments)
- **042–044**: Foundation crates (slash command registry, shared primitives, subagent lifecycle)
- **045**: Agent interoperability protocol gap analysis
- **046**: MARCH Proposer+Checker quality pipeline
- **047**: CLI execution modes (--bare, --json, -y, /loop, /recap)
- **048**: SLM cost metrics survey and CPS metric contract
- **049**: Agent god-object decomposition (Services aggregator + AgentRuntime newtype)
- **050**: Security capability governance (tool scoping + trajectory sentinel + Phase 2 ShadowSentinel safety probe + classify_tool bare-ID fix + CapSeal sketch) [Phase 1+2 implemented]
- **051**: Gonka.ai Phase 1 — GonkaGate hosted gateway (CompatibleProvider, wizard, vault key) [implemented]
- **052**: Gonka.ai Phase 2 — native network transport (GonkaProvider, ECDSA signing, EndpointPool, chat_with_tools, chat_typed) [implemented]
- **053**: SpeculationEngine — speculative tool execution (SSE decoding path, PASTE skill activation, ToolStartEvent{speculative:true})
- **055**: Cocoon distributed compute integration — CocoonProvider, CocoonClient, `zeph cocoon doctor`, TUI palette entries, vault key ZEPH_COCOON_ACCESS_HASH
---
## Business and Requirements Documentation
| Doc | Contents |
|---|---|
| `BRD.md` | Business Requirements Document — what Zeph is, why it exists, target personas, business constraints, success criteria |
| `SRS.md` | Software Requirements Specification (ISO/IEC/IEEE 29148:2018) — all functional requirements grouped by subsystem, EARS notation, traceability to BRD |
| `NFR.md` | Non-Functional Requirements (ISO/IEC 25010:2011) — measurable quality targets for performance, reliability, security, maintainability, portability, usability, compatibility, and safety |
## System Invariants
| Doc | Contents |
|---|---|
| `001-system-invariants/spec.md` | Cross-cutting architectural invariants |
## Feature Docs
| Doc | Feature | Crate |
|---|---|---|
| `002-agent-loop/spec.md` | Agent loop, turn lifecycle, context pressure, HiAgent subgoal-aware compaction | `zeph-core` |
| `003-llm-providers/spec.md` | LlmProvider trait, AnyProvider, prompt caching, configurable `CacheTtl` (ephemeral/1h) | `zeph-llm` |
| `004-memory/spec.md` | SQLite + Qdrant, compaction, semantic response cache, anchored summarization, compaction probe, importance scoring, A-MAC admission control, MemScene consolidation, multi-vector chunking, GAAMA episode nodes, BATS budget hints, Focus compression, SleepGate forgetting pass, persona memory, trajectory memory, category-aware memory, TiMem tree, microcompact, autoDream, MagicDocs, embed backfill batching | `zeph-memory` |
| `004-memory/004-7-memory-apex-magma.md` | APEX-MEM append-only MAGMA: edge supersession, ontology normalization, SYNAPSE conflict resolution (#3223); BeliefMem probabilistic pre-commitment edge layer with Noisy-OR accumulation, temporal decay, promotion threshold (#3706) | `zeph-memory` |
| `004-memory/004-8-memory-typed-pages.md` | ClawVM typed page compaction: PageType classification, minimum-fidelity invariants, compaction audit log (#3221) | `zeph-context`, `zeph-memory` |
| `004-memory/004-9-memory-write-gate.md` | MemReader write quality gate: three-signal scorer, rule-based MVP, optional LLM scoring (#3222) | `zeph-memory` |
| `004-memory/004-10-memory-memmachine-retrieval.md` | MemMachine retrieval-depth-first memory: retrieval depth config, search prompt templates, query bias correction, episode preservation (#3325) | `zeph-memory` |
| `004-memory/004-11-memory-hela-mem.md` | HeLa-Mem Hebbian learning: edge weight reinforcement, periodic consolidation, spreading activation retrieval (#3324) | `zeph-memory` |
| `004-memory/004-12-memory-reasoning-bank.md` | ReasoningBank: self-judge + distillation pipeline, strategy embedding store, context preamble injection (#3312) | `zeph-memory`, `zeph-core` |
| `004-memory/004-13-memory-memcot.md` | MemCoT: SemanticStateAccumulator, Zoom-In evidence localization, Zoom-Out causal expansion (#3592) | `zeph-memory` |
| `004-memory/004-14-memory-tiering-rfc-decision.md` | RFC #4217 decision: memory tiering architecture analysis (MEMTIER, BudgetMem, Multi-Layer, LCM, MemRouter); adopt frequency signal + tier-aware gating + cost-aware routing (#4217) | `zeph-memory` |
| `004-memory/004-15-memory-skill-coevolution-rfc-decision.md` | RFC #4218 decision: memory–skill coevolution analysis (MemQ, δ-mem, EvolveMem, SAGE-GraphMem, NanoResearch, Cognifold); adopt Cognifold idle-time folding + EvolveMem feedback routing; defer MemQ to P3 (#4218) | `zeph-memory`, `zeph-skills` |
| `005-skills/spec.md` | SKILL.md format, registry, matching, hot-reload, skill trust governance, two-stage matching, Wilson score confidence intervals, hub install pipeline, agent-invocable skills (`invoke_skill`) | `zeph-skills` |
| `006-tools/spec.md` | ToolExecutor, CompositeExecutor, TAFC, schema filter, result cache, dependency graph, tool invocation phase taxonomy, native `tool_use` only; `invoke_skill`/`load_skill` utility-gate exemption | `zeph-tools` |
| `007-channels/spec.md` | Channel trait, AnyChannel dispatch, streaming, channel feature parity, `stream_interval_ms` (Bot API 10.0, #3727); `TelegramApiClient` 30s `REQUEST_TIMEOUT` on reqwest client (#3780); Telegram reaction moderation tools `telegram_delete_reaction` / `telegram_delete_all_reactions` (#3770); CJK false-positive fix in FeedbackDetector; `send_status` added to Discord and Slack adapters (#4228) | `zeph-channels` |
| `007-channels/007-1-telegram-guest-mode.md` | Telegram Guest Mode — `guest_message` update handling, `answerGuestQuery` routing, `allowed_users` access control, single-shot streaming (#3729) | `zeph-channels`, `zeph-core`, `zeph-config` |
| `007-channels/007-2-telegram-bot-to-bot.md` | Telegram Bot-to-Bot — `setManagedBotAccessSettings` startup, `allowed_bots` authorization, reply-chain loop prevention, `is_from_bot` metadata (#3730) | `zeph-channels`, `zeph-core`, `zeph-config` |
| `008-mcp/spec.md` | MCP client, server lifecycle, semantic tool discovery, per-message pruning cache, injection detection, tool collision detection, caller identity propagation, tool quota, structured error codes, OAP authorization, elicitation (2025-06-18) | `zeph-mcp` |
| `009-orchestration/spec.md` | DAG planner, DagScheduler, AgentRouter, /plan command, plan template cache, VMAO adaptive replanning, cascade-aware DAG routing, VeriMAP predicate gate, AdaptOrch topology advisor, CoE entropy routing, graph persistence in scheduler loop | `zeph-orchestration` |
| `010-security/spec.md` | Vault, shell sandbox, content isolation, SSRF protection, IPI defense, PII NER circuit breaker, cross-tool injection correlation, AgentRFC protocol audit, MCP→ACP boundary enforcement, credential env-var scrubbing, file permission hardening (`fs_secure`), Seatbelt deny-first secret-path rules | cross-cutting |
| `010-security/010-5-egress-logging.md` | Egress logging sub-spec: `EgressEvent` per outbound HTTP call, `AuditEntry.correlation_id`, bounded mpsc telemetry (256 + drop counter), TUI Security panel surface | `zeph-tools`, `zeph-core`, `zeph-tui` |
| `010-security/010-6-vigil-intent-anchoring.md` | VIGIL verify-before-commit sub-spec: pre-sanitizer regex tripwire with Block/Sanitize action, per-turn `current_turn_intent`, subagent exemption, non-retryable blocks via `error_category="vigil_blocked"` | `zeph-core`, `zeph-tools`, `zeph-config` |
| `010-security/010-7-shadow-memory-guardrail.md` | Shadow Memory Guardrail sub-spec: MAGE multi-turn threat detection (goal hijacking via accumulating risk scores), SafeHarbor hierarchical guardrail tree (entropy-based evolution, adaptive rule injection) | `zeph-sanitizer`, `zeph-memory`, `zeph-agent-tools`, `zeph-core` |
| `011-tui/spec.md` | ratatui dashboard, spinner rule for background operations, TuiChannel, RenderCache, embed backfill progress, multi-session `SessionRegistry`, `/session` commands, compact paste indicator; Fleet panel (`f` key, #3884); reasoning token tracking; terminal title (#4354); fleet session lifecycle wiring (#4363) | `zeph-tui` |
| `012-graph-memory/spec.md` | Entity graph, BFS recall, community detection, MAGMA typed edges, SYNAPSE spreading activation | `zeph-memory` |
| `004-memory/004-6-graph-memory.md` | Graph memory sub-spec (concise reference within 004-memory): MAGMA typed edges, SYNAPSE config, A-MEM link weights, key invariants | `zeph-memory` |
| `013-acp/spec.md` | ACP transports, session management, permissions, fork/resume, session/close handlers, capability advertisement, /agent.json endpoint | `zeph-acp` |
| `014-a2a/spec.md` | A2A protocol, agent discovery, JSON-RPC 2.0, IBCT (Invocation-Bound Capability Tokens), HMAC-SHA256 signatures | `zeph-a2a` |
| `015-self-learning/spec.md` | FeedbackDetector (multi-language), Wilson score, trust model, SAGE RL cross-session reward, ARISE trace improvement, STEM pattern-to-skill migration, ERL experiential learning | `zeph-skills` |
| `016-agent-feedback/spec.md` | Implicit correction detection: `FeedbackDetector` (regex-only, 7 languages, dual anchoring tiers), `JudgeDetector` (LLM judge with adaptive thresholds, sliding-window rate limiter 5/min), four correction kinds (explicit rejection, alternative request, repetition, self-correction), CJK limitations | `zeph-agent-feedback` |
| `017-output-filtering/spec.md` | FilterPipeline, CommandMatcher, SecurityPatterns | `zeph-tools` |
| `018-index/spec.md` | AST indexing, semantic retrieval, repo map generation | `zeph-index` |
| `019-scheduler/spec.md` | Cron scheduler, SQLite persistence, CLI subcommands (list/add/remove/show) | `zeph-scheduler` |
| `020-gateway/spec.md` | HTTP webhook ingestion, bearer token authentication | `zeph-gateway` |
| `021-config-loading/spec.md` | Config resolution order, mode-agnostic defaults, environment overrides, `--migrate-config --in-place` idempotency | `zeph-core` |
| `022-zeph-context/spec.md` | `zeph-context` crate: `ContextBudget` token arithmetic, `CompactionState` state machine, `ContextAssembler` parallel fetch, `PreparedContext` output; extracted from `zeph-core` | `zeph-context` |
| `023-config-simplification/spec.md` | Provider Registry Architecture: canonical `[[llm.providers]]` format, ProviderEntry schema, routing strategies, LinUCB bandit routing, cost-weight dial, memory-augmented routing | `zeph-config`, `zeph-core` |
| `024-complexity-triage-routing/spec.md` | Pre-inference complexity classification routing, ComplexityTier, TriageRouter, context escalation, metrics | `zeph-llm`, `zeph-config`, `zeph-core` |
| `025-multi-model-design/spec.md` | Multi-model design principle: complexity tiers, `*_provider` subsystem reference pattern, STT unification | cross-cutting |
| `026-classifiers/spec.md` | Candle-backed ML classifiers: injection detection, PII detection, LlmClassifier for feedback, unified regex+NER sanitization pipeline | `zeph-classifiers` |
| `027-tui-subagent-management/spec.md` | Interactive TUI subagent sidebar (a key), j/k navigation, Enter loads transcript, Esc returns, Tab cycling; automatic view switch to foreground subagent on spawn + return to Main on completion via `ForegroundSubagentStarted`/`ForegroundSubagentCompleted` `AgentEvent` variants (#3764) | `zeph-tui` |
| `028-runtime-layer/spec.md` | RuntimeLayer middleware with before_chat/after_chat/before_tool/after_tool hooks, NoopLayer, LayerContext, unwind guards; plugin config overlay merge (tighten-only) | `zeph-core` |
| `029-hooks/spec.md` | Reactive hooks: cwd_changed / file_changed / permission_denied / turn_complete / pre_tool_use / post_tool_use events, set_working_directory tool, FileChangeWatcher, ZEPH_TOOL_NAME / ZEPH_TOOL_ARGS_JSON / ZEPH_SESSION_ID env vars (#3725); pre_tool_use fires before utility gate (#3738); permission_denied fires at all gate denial points in tier loop (#3779); turn_complete McpTool hooks wired to live MCP dispatch (#3776); post_tool_use output replacement + duration_ms (#3998); inline hooks in config.toml (#3885, #4252) | `zeph-core` |
| `030-feature-flags/spec.md` | Feature flag decision rules, surviving flag inventory (22 flags), bundle definitions (desktop, ide, server, full) | `Cargo.toml`, cross-cutting |
| `031-tui-slash-autocomplete/spec.md` | Inline autocomplete dropdown in TUI Insert mode, reuses filter_commands registry, Tab/Enter accepts, Esc dismisses | `zeph-tui` |
| `032-database-abstraction/spec.md` | PostgreSQL backend, zeph-db crate, DatabaseDriver trait, Dialect trait, sql!() macro, migrations, CLI subcommands | `zeph-db`, cross-cutting |
| `033-handoff-skill-system/spec.md` | Skill-based YAML handoff protocol for inter-agent communication, structured skill exchange | `zeph-orchestration` |
| `034-subagent-context-propagation/spec.md` | Gap analysis and resolution plan for `/agent spawn` context propagation; orphaned ToolUse/ToolResult pairs pruned by `trim_parent_messages` (#3760); token budget estimated by `estimate_parts_size` (#3761) | `zeph-subagent`, `zeph-core` |
| `035-zeph-bench/spec.md` | Benchmark harness: BenchmarkChannel, dataset loaders, CLI `zeph bench run`, memory isolation, deterministic mode, baseline comparison | `zeph-bench` |
| `036-profiling/spec.md` | Two-tier telemetry (Tier 1: local chrome traces, Tier 2: OTLP + Pyroscope), per-span `#[instrument]` macros, allocation tracking, InstrumentedChannel wrappers, system metrics; zero-overhead when disabled | cross-cutting |
| `037-prometheus-metrics/spec.md` | Prometheus `/metrics` endpoint, OpenMetrics export, ~25 gauge/counter metrics from MetricsSnapshot, feature-gated with gateway | `zeph-gateway`, binary |
| `038-config-schema/spec.md` | Canonical TOML schema reference: all top-level sections, validation rules, env-var override table, `--migrate-config` migration mechanism | `zeph-config` |
| `039-vault/spec.md` | Vault & Secret Management: VaultProvider trait, age encryption backend, env backend (testing), zeroize-on-drop guarantee, vault config schema, key invariants, multi-recipient vaults | `zeph-vault` |
| `040-background-task-supervisor/spec.md` | (Proposed) Supervised Background Task Manager: AgentTaskSupervisor, task priority classes, queue depth limits, turn-boundary cleanup, metrics (`bg_inflight`, `bg_dropped`) | `zeph-core` |
| `041-sanitizer/spec.md` | Content Sanitizer: spotlighting pipeline, regex injection detection, PII scrubber, guardrail filter, quarantined summarizer, response verification, exfiltration guards, memory validation, causal analysis (eight-layer defense-in-depth) | `zeph-sanitizer` |
| `042-experiments/spec.md` | Experiments & Runtime Feature Gating: `[experiments]` config section, ExperimentConfig, rollout percentage, experiment results reporting, CLI subcommands; distinct from compile-time feature flags | `zeph-experiments` |
| `043-zeph-commands/spec.md` | Slash command registry, `CommandHandler<Ctx>` object-safe trait, `CommandRegistry` with longest-word-boundary dispatch, `ChannelSink` abstraction, static `COMMANDS` list; `/recap` command, `/session` TUI commands; no dependency on `zeph-core` | `zeph-commands` |
| `044-zeph-common/spec.md` | Shared primitives: `Secret` (zeroize-on-drop), `ToolName` (Arc<str>), `SessionId` (UUID v4), `ToolDefinition`, `SkillTrustLevel`, `PolicyLlmClient`; no `zeph-*` peer dependencies | `zeph-common` |
| `045-subagent-lifecycle/spec.md` | Full `zeph-subagent` crate: `SubAgentDef` parsing, `SubAgentManager` spawning and concurrency cap, `PermissionGrants` TTL, `FilteredToolExecutor` policy gate (case-insensitive tool ID normalization via `normalize_tool_id`, #3765), `MemoryAwareExecutor` for `memory: user` subagents (#3771), transcript JSONL persistence, lifecycle hooks, memory injection | `zeph-subagent` |
| `046-interop-protocol-gaps/spec.md` | Agent interoperability protocol gap analysis (arXiv:2505.02279): capability matrix for MCP, ACP, A2A, ANP vs. Zeph; protocol selection guidance; ANP as P4 research; ACP re-negotiation as P3 follow-up | cross-cutting |
| `047-march-quality/spec.md` | MARCH Proposer+Checker self-check pipeline: post-response factual consistency, information-asymmetry checker, `self-check` feature flag, per-turn `MarchVerdict`, Prometheus metrics (#3226) | `zeph-core` |
| `048-cli-modes/spec.md` | CLI execution modes: `--bare` (skip scheduler/indexer/eviction), `--json` (JSONL event stream), `-y` (auto-approve), `/loop` command (supervised loop with inline errors), `/recap` command (#3170, #3218) | `zeph-channels`, binary |
| `008-mcp/008-4-elicitation.md` | MCP server-driven elicitation (protocol 2025-06-18): `elicitation/create` routing to active channel, sensitive field warnings, Sandboxed trust hard-reject, Telegram timeout, URL field decline (#3218) | `zeph-mcp`, `zeph-channels` |
| `UX/mention-routing.md` | @agent mention routing: Goose pattern analysis, feasibility for Zeph TUI/A2A, verdict to defer pending `AgentRegistry` infrastructure (#3327) | `zeph-core`, `zeph-tui`, `zeph-a2a` |
| `049-slm-cost-metrics/spec.md` | SLM survey findings (arXiv:2510.03847), CPS (cost per successful task) metric contract, `record_successful_task()` / `cps()` API, daily reset semantics | `zeph-core` |
| `050-agent-decomposition/spec.md` | Agent god-object Phase 2 (#3509): split `Agent<C>` 25+ direct sub-state fields into `services: Services` (background subsystems) and `runtime: AgentRuntime` (config, lifecycle, providers, metrics, debug, instructions); pure refactor, no API change, separately borrowable; `TurnContext` boundary sketched for P2-prereq-3 | `zeph-core` |
| `051-security-capability-governance/spec.md` | Capability scoping (`ScopedToolExecutor` + per-task-type allow-lists, #3563), `TrajectorySentinel` multi-turn risk accumulator with decay (#3570), Phase 2: `ShadowSentinel` safety probe — `SafetyProbe` trait, `LlmSafetyProbe`, `ShadowProbeExecutor`, `safety_shadow_events` table, `classify_tool` bare-ID fix (#3705, #3735, #3739, #3742, #3744, #3745), CapSeal/SUDP `VaultBroker::propose_operation` Phase-3 research sketch (#3569); built-in tool id `builtin:` normalization at `ScopedToolExecutor` dispatch boundary (#3778) | `zeph-tools`, `zeph-core` |
| `052-gonka-gateway/spec.md` | Phase 1: gonka.ai inference via GonkaGate hosted gateway — zero new Rust code, `CompatibleProvider` reuse, wizard branch, vault key `ZEPH_COMPATIBLE_GONKAGATE_API_KEY` | `zeph-llm`, `zeph-config` |
| `053-gonka-native/spec.md` | Phase 2: native gonka network transport — `GonkaProvider`, ECDSA secp256k1 signing (`RequestSigner`), `EndpointPool` round-robin fail-skip, `send_signed_with_retry`, `chat_with_tools`, `chat_typed`, `zeph gonka doctor` | `zeph-llm`, `zeph-config` |
| `054-speculation-engine/spec.md` | `SpeculationEngine` — speculative tool execution: `PartialJsonParser` SSE decoding path, PASTE skill activation, `try_dispatch`/`try_commit`/`end_turn` API, `ToolStartEvent{speculative:true}`, `DynExecutor` confirmation delegation | `zeph-core`, `zeph-tools` |
| `056-cocoon/spec.md` | Cocoon distributed compute integration — `CocoonProvider`, `CocoonClient`, health check via `/stats`, model listing via `/v1/models`, `zeph cocoon doctor` (6 checks), `--init` wizard branch, TUI `/cocoon status` + `/cocoon models`, vault key `ZEPH_COCOON_ACCESS_HASH`; all RA-TLS/TON handled by C++ sidecar | `zeph-llm`, `zeph-config` |