Program: Coven Automations v1 — reliable, identity-bound familiar routines

[BunsDev]

Outcome

Ship Coven Automations v1 as the canonical local-first system for durable recurring familiar work: schedules survive restarts, occurrences are fenced and recoverable, every execution is freshly bound to identity and authority, runtimes remain replaceable workers, and Cave/SDK clients observe one Coven-owned truth.

This is not a generic cron wrapper. It is the automation profile of the OpenCoven identity → authority → orchestration → runtime → oversight stack.

Final implementation assessment — 2026-08-30

What is already real

The foundation under #816 has materially landed:

• versioned Coven-owned routine definitions;
• SQLite definition, occurrence, lease, and run records;
• RRULE-backed daily/weekly planning;
• unique occurrence fencing;
• bounded claim leases and expired-lease recovery;
• latest-only misfire handling and overlap refusal;
• daemon-side recurring tick and scheduled dispatch;
• one shared runtime-launch path for scheduled and manual runs;
• familiar ID propagation, bounded run logs, and atomic output delivery;
• routine health, run history, and non-destructive paused legacy import;
• coven.automations.* control actions;
• Cave migration from direct Codex ownership to the Coven control plane.

Why this is not yet a stable v1 contract

The current implementation is a strong local scheduler foundation, but it is not yet safe to describe as a production-grade unattended familiar automation protocol:

1. The wire contract is implicit in Rust structs and ad hoc JSON payloads rather than independently versioned schemas and conformance vectors.
2. A routine is still primarily a schedule + prompt, not a modular trigger / condition / authorized action model.
3. Familiar binding is an optional string; exact familiar root/revision, principal authorization, capability grants, approval path, and exercised-authority receipts are not yet normative.
4. The scheduler uses a fixed wall-clock thread cadence and lacks a complete virtual-time, DST, cancellation, retry/backoff, shutdown, leader/fencing, and clock-jump contract.
5. Control actions can report transport-level acceptance while embedding domain failure inside an event payload; typed failure semantics and request idempotency need to become protocol invariants.
6. There is no supported SDK automation surface, canonical event/changefeed subscription, or independent receipt verifier.
7. Cross-repository conformance, chaos/restart certification, load/SLO evidence, and operator-grade diagnostics are incomplete.
8. Cave has migrated ownership, but complete oversight—authority, attempts, recovery, retry/cancel, stale identity, and compatibility retirement—still needs a deliberate product gate.

Program assessment: foundation-ready, not v1-certified. Unattended external side effects remain out of scope until the identity/authority and conformance gates pass.

Operational issue map

Foundation and program control

• Native familiar automations: replace harness-owned schedules with durable Coven routines #816 — reconcile and close the native durable-routine foundation with exact landed/test evidence.
• P0 control: Operationalize Coven Automations v1 through Cave’s canonical Beads graph and GitHub mirrors #859 — establish the reviewed Beads graph, one-to-one GitHub mappings, roadmap artifact, and drift checks.

P0 — protocol and safety

• P0: Specify coven.automations.v1 schemas, state machines, idempotency, and changefeed #855 — versioned coven.automations.v1 schemas, lifecycle state machines, adoption/idempotency, typed errors, and durable changefeed.
• P0: Harden automation time, retries, cancellation, fencing, and crash recovery #856 — deterministic time, IANA timezone/DST, retry classification/backoff, cancellation, scheduler leadership/fencing, crash recovery, backpressure, and diagnostics.
• P0 profile: Define universal familiar embodiment binding for automation and direct runs familiar-contract#17 — universal familiar embodiment binding for direct, automated, and Psyche-delegated sessions.
• P0 profile: Define automation authority, approvals, and degrade-to-proposal semantics coven-threads#29 — operation-specific automation authority, approvals, risk/capability policy, and degrade-to-proposal semantics.
• P0: Bind automation runs to principal authority, familiar revisions, capabilities, approvals, and receipts #857 — integrate authenticated principal authority, exact familiar revision, runtime capabilities, approvals, and verifiable Automation Receipts into Coven dispatch.
• P0: Build automations conformance, chaos, SLO, and operator diagnostics #858 — independent conformance runner/vectors, chaos/restart tests, security/privacy profiles, load/SLO gates, exact-artifact certification, and operator diagnostics.

P1 — supported ecosystem

• P1: Add constrained Coven Automations SDK types, subscriptions, verification, and authority-aware commands sdk#80 — constrained SDK types, read/verify/subscribe first, then authority-aware adopted commands.
• P1: Complete Coven Automations oversight, approvals, recovery, and compatibility retirement coven-cave#5217 — complete oversight, approvals, recovery controls, truthful stale/degraded state, and Codex compatibility retirement.
• P1: Define the Psyche adapter for automation-triggered orchestration without owning schedules psyche#18 — automation-triggered orchestration adapter without moving schedule or occurrence ownership into Psyche.
• P1: Publish Coven Automations v1 protocol, operator, migration, and troubleshooting documentation coven-docs#76 — protocol, operator, migration, security/privacy, compatibility, and troubleshooting documentation with executable examples.
• P1: Add reusable Coven Automations conformance, contract-drift, and roadmap checks .github#2 — reusable producer/consumer canaries, conformance profiles, evidence packets, roadmap drift checks, and compatibility-ledger generation.

P2 — deliberate expansion after v1 certification

• Event, condition, dependency, and webhook triggers.
• Multi-host routing and bounded hosted execution.
• Explicit overlap/misfire variants beyond safe v1 defaults.
• Declarative action adapters beyond familiar prompt execution.
• Federated/team synchronization, continuity proofs, and certification governance.

P2 work must not become an implicit prerequisite for the local recurring-routine v1.

Current execution order

1. Operationalize the graph: complete P0 control: Operationalize Coven Automations v1 through Cave’s canonical Beads graph and GitHub mirrors #859, inspect/reuse any existing Native familiar automations: replace harness-owned schedules with durable Coven routines #816 Bead, designate one Beads writer/schema owner, and land the mapping/roadmap through review.
2. Ratify the public contract: complete P0: Specify coven.automations.v1 schemas, state machines, idempotency, and changefeed #855 before downstream clients harden hand-authored JSON shapes.
3. Parallelize independent foundations: progress P0: Harden automation time, retries, cancellation, fencing, and crash recovery #856, P0 profile: Define universal familiar embodiment binding for automation and direct runs familiar-contract#17, and P0 profile: Define automation authority, approvals, and degrade-to-proposal semantics coven-threads#29 in parallel against pinned draft artifacts.
4. Integrate trust at dispatch: complete P0: Bind automation runs to principal authority, familiar revisions, capabilities, approvals, and receipts #857 using the ratified identity and authority profiles; no string-only fallback.
5. Certify the core: complete P0: Build automations conformance, chaos, SLO, and operator diagnostics #858 against packed/exact artifacts with deterministic, restart, duplicate, security, privacy, and load evidence.
6. Graduate clients and orchestration: land SDK read/verify/subscribe, Cave oversight, and the Psyche adapter against immutable canaries.
7. Publish and enforce: complete Docs and .github compatibility/readiness workflows, then issue one exact-release go/no-go packet.

Canonical ownership

Layer	Owns	Must not own
Familiar Contract / continuity profile	familiar root, revision, same-familiar continuity, embodiment binding	schedules, run state, or runtime dispatch
Coven Threads / authority profile	protected-action classification, capability/approval semantics, authority evidence	clock liveness or occurrence planning
Psyche	multi-step orchestration invoked by an occurrence when needed	canonical schedules or a second automation ledger
Coven	definitions, planning, occurrences, runs/attempts, leases, dispatch, recovery, receipts, changefeed	familiar identity authorship or UI-local truth
coven-runtimes	runtime capability truth and conformance	scheduling or product authority
SDK	constrained typed clients, subscriptions, verification, authority-aware requests	independent persistence or inferred permissions
Cave	oversight, proposal/creation flows, approvals, diagnostics, recovery controls	scheduler policy or run-state authorship
Beads	implementation dependency graph, assignment, status, and evidence references	runtime definitions, occurrences, runs, approvals, artifacts, or receipts
GitHub	public outcomes, rationale, acceptance gates, and durable delivery links	implementation execution state or runtime truth

Non-negotiable invariants

• Coven is the only canonical automation definition and lifecycle authority.
• At-least-once observation is acceptable; duplicate execution of one fenced occurrence is not.
• No state is called succeeded until runtime outcome and required delivery commit are durably recorded.
• Every mutating request has stable adoption/idempotency semantics.
• Every run resolves current familiar identity, runtime capability, principal authority, and approval requirements at dispatch time.
• No creation-time credential, approval, identity revision, or capability decision is silently reused.
• Ambiguous mutating work enters explicit recovery; it is never automatically replayed as though nothing happened.
• Unknown, stale, malformed, revoked, or unavailable authority inputs fail closed.
• Cave and SDK render daemon state; neither synthesizes successful, running, authorized, or healthy state.
• Logs, events, receipts, diagnostics, and tracker evidence are bounded and privacy-classified.

Release gates

Gate A — durable local scheduler

• Deterministic schedule, timezone/DST, misfire, duplicate, restart, lease, cancellation, timeout, retry, and delivery tests pass.
• A daemon crash at every consequential boundary converges without silent loss, false success, or duplicate execution.
• Startup, shutdown, clock jumps, sleep/wake, definition changes, and competing local processes have explicit behavior.

Gate B — identity and authority

• Every dispatched run pins authenticated principal authority, familiar root/revision, definition revision, occurrence fence, runtime descriptor, capability/approval evidence, and adopted request.
• Revoked, stale, ambiguous, incompatible, or unauthorized inputs cannot dispatch.
• External effects remain proposal/approval-gated until a narrowly scoped unattended grant exists.
• Every terminal run emits a privacy-classified, independently verifiable Automation Receipt.

Gate C — public contract and interoperability

• Versioned schemas and golden vectors are independent of implementation internals.
• SDK, Cave, Psyche, identity, authority, and runtime consumers pass immutable cross-repository canaries.
• Additive evolution, negative capability negotiation, packed artifacts, and reconnect/replay behavior are proven.

Gate D — operations and release evidence

• Missed, duplicated, stuck, unauthorized, stale-identity, repeatedly failing, ambiguous, cancelled, and delivery-failed cases are diagnosable without raw SQLite edits.
• Retention, redaction, backup/recovery, incident runbooks, load/SLOs, and privacy/security profiles are exercised.
• A machine-readable exact-release evidence packet supports an independent go/no-go decision.
• Beads/GitHub mappings and statuses are reconciled with no orphan P0 outcome.

Beads operating contract

The canonical graph is:

#816 foundation
  ├─ #855 protocol
  ├─ #856 scheduler reliability
  └─ identity + authority profiles
       ├─ familiar-contract#17
       └─ coven-threads#29
              ↓
            #857 integration

#855 + #856 + #857 -> #858 certification
#858 -> exact v1 release gate

#855 -> sdk#80 read/types/subscriptions
#855 + #857 -> sdk#80 authority-bearing commands
#855 + #856 + #857 -> cave#5217
#855 + #857 -> psyche#18
#858 + all consumers -> docs#76 + .github#2

Tracker rules:

• one Bead maps to one public GitHub outcome;
• Beads owns implementation dependencies, assignment, priority, status, and execution evidence references;
• GitHub owns durable public outcomes, rationale, acceptance gates, PR/release links, and cross-repository decisions;
• generated mirrors are reconciled from Beads and are not hand-edited into a competing tracker;
• Beads files change through reviewed branches/PRs, with one schema owner/writer per migration;
• tracker data is never queried as production automation truth;
• drift checks flag state/priority disagreement, unknown parent mapping, orphan P0 work, missing evidence, and closed-Bead/open-outcome disagreement.

Program metrics

Track at least:

• occurrence planning lag and start latency;
• missed-occurrence and duplicate-dispatch count;
• lease expiry/recovery count and recovery latency;
• run success/failure/cancel/timeout/recovery-required rates;
• consecutive-failure and quarantine count;
• retry/backoff behavior by failure class;
• identity/authority/capability/approval refusal count;
• delivery-commit and receipt-verification failure count;
• scheduler pass duration, queue depth, database contention, and storage growth;
• event/changefeed lag and reconnect replay correctness;
• bounded log/receipt size and redaction violations;
• Beads/GitHub roadmap drift;
• SDK/Cave/Psyche compatibility matrix status;
• deterministic, chaos, security/privacy, load, and exact-release conformance status.

Definition of done

Coven Automations v1 is complete only when:

1. Native familiar automations: replace harness-owned schedules with durable Coven routines #816 is reconciled as the landed scheduler foundation;
2. all P0 protocol, reliability, identity, authority, integration, certification, and tracker-control outcomes pass with exact evidence;
3. supported SDK, Cave, Psyche, Docs, and organization-enforcement surfaces consume the same immutable contracts;
4. the Beads/GitHub graph is synchronized;
5. one release candidate passes clean-clone, deterministic-time, crash/restart, duplicate/fencing, cross-repository, security, privacy, migration, packed-artifact, operational, and load/SLO certification.

Passing unit tests or observing one scheduled run is evidence, but not certification.

Evidence pointers — refreshed 2026-09-01

• Foundation implementation and landed commits: docs/superpowers/plans/2026-08-30-coven-automations-v1-program-status.md maps the foundation claims to crates/coven-cli/src/automations/{definition,store,rrule,schedule,occurrences,daemon_tick,runner,health,runs,import_legacy}.rs, crates/coven-cli/src/control_plane.rs, and crates/coven-cli/src/api.rs, with the landed PR/commit series.
• Canonical dependency order: docs/roadmaps/coven-automations-v1.md and docs/roadmaps/coven-automations-v1.mapping.json own the reviewed graph and release gates; the issue body remains the public program rollup.
• Versioned wire-contract artifacts: commit c4c9ccb added the independent schemas, lifecycle state machines, typed errors, compatibility rules, TypeScript projection, and golden vectors under spec/coven-automations/v1/. This is landed specification evidence, not by itself v1 certification; P0: Specify coven.automations.v1 schemas, state machines, idempotency, and changefeed #855 remains open until its review and test/canary gates are reconciled.
• Certification acceptance artifact: spec/coven-automations/v1/conformance-manifest.json is the machine-readable checklist and currently declares releaseState: "proposed" and productionReady: false. P0: Build automations conformance, chaos, SLO, and operator diagnostics #858 owns the exact-release evidence packet that resolves every requiredSuites entry to an immutable artifact digest and result, records Coven/SDK/Cave packed-artifact canaries plus authority/privacy/operator evidence, and is the only artifact allowed to advance those fields for the Program: Coven Automations v1 — reliable, identity-bound familiar routines #854 go/no-go rollup.