coven-threads is OpenCoven's protected-authority validator. It defines the
typed gate, weave, approval, audit-schema, and portability contracts imported by
the trusted coven daemon.
This root guide is a router. Keep temporary incidents, implementation diaries, and mutable interaction history out of it.
This repository owns:
- protected-surface mutation verdict semantics;
- Thread / Weave / Strand / Channel validation contracts;
- approval-path, veto-window, replay, and typed close semantics;
- the
ward_auditrecord and SQLite schema/migration contract; .weaveportability and conformance vectors.
This repository does not own:
- familiar identity definition or identity continuity (
familiar-contract); - principal credential issuance, rotation, recovery, or daemon authentication;
- filesystem writes, SQLite connections, staging, scheduling, apply, or restart
recovery (
coven); - task/lane/lease/attempt lifecycle (
psyche); - UI policy or approval authority (
coven-cave).
Any change that creates a second canonical writer for one of those concerns must stop for an architecture decision.
When sources disagree, use this order:
familiar-contract/rfcs/RFC-0001-familiar-contract.mdfor familiar identity and Ward requirements;- frozen or active decision records under
specs/for Threads semantics; - public Rust contracts and conformance vectors in
crates/coven-threads-core; - explanatory material under
docs/.
The daemon is the runtime trust boundary. A client, prompt, descriptor, model, or familiar self-report is never authority merely because it names an allowed state.
- Read
agent/manifest.yaml. - Read
docs/phases.mdfor the honest delivery ledger. - Read the relevant decision record under
specs/. - For boundary work, read
docs/testing/e2e-contract.mdande2e/compatibility.toml. - Inspect the exact public types, predicates, SQL, and tests before proposing a change.
bash scripts/agent-bootstrap.sh
bash scripts/agent-check.sh fast
bash scripts/agent-check.sh fullThe fast gate verifies prerequisites, pinned toolchain parity, repository contract metadata, the privacy and secret guards, formatting, Clippy with warnings denied, and library tests. The full gate runs the complete locked workspace suite.
Both gates run the guards behind the required Privacy policy guard and
Secret scanning checks, so a local failure is reproducible before pushing.
Two things to know:
- The guards read the git index, not the working tree. Stage a fix before re-running, or it will not be scanned. The gate warns when tracked files carry unstaged changes.
- The secret scans need the checksum-pinned
gitleaks. Because the manifest setsnetwork_policy: bootstrap-only, the gate never fetches it; if it is absent the gate says so and continues, and CI still enforces the check. Install it withbash scripts/install-gitleaks.sh "$PWD/.tooling/bin"and put that directory onPATH.
Manifest parsing needs Python 3.11+ for tomllib. macOS ships 3.9 at
/usr/bin/python3, so ensure a newer interpreter comes first on PATH.
Useful targeted suites:
cargo test --locked -p coven-threads-core --test rfc0001_s5_conformance
cargo test --locked -p coven-threads-core --test c7_roundtrip
cargo test --locked -p coven-threads-core --test phase5_retired_ward_corpus
cargo nextest run --locked --workspace --profile cicargo test --locked --workspace remains the compatibility source of truth.
Nextest adds JUnit and flake telemetry; it does not redefine test semantics.
crates/coven-threads-core/src/automation_authority ports
profiles/automation-authority/v1/validator.mjs: every operation the
conformance manifest names, checked against all 132 vectors. A change to any
function there, or to the vectors, updates the Rust port in the same pull
request. Run:
cargo test --locked -p coven-threads-core --test automation_authority_vectors
cargo build --locked -p coven-threads-core --example automation_authority_batch
node scripts/automation-authority-differential.mjs target/debug/examples/automation_authority_batchThe differential hands the port every case as serialized text, which crosses
strict_parse_json before any operation, and rewrites each vector body at the
text level (duplicate and escaped keys, number spellings, lone surrogates) so
the two parsers are compared on the same bytes. A change to the batch
example's input protocol updates the script in the same pull request. On a
mismatch the script keeps the failing cases and prints the directory and a
reproduction command.
Coven builds serde_json with arbitrary_precision, which Cargo unifies into
this crate. The gate therefore runs the vectors and the differential a second
time with --features serde_json/arbitrary_precision; the script prints which
configuration it compared.
Treat changes to identity predicates, validation, approvals, audit SQL, migrations, portability, release workflows, or frozen specs as R4:
- unknown, stale, unauthenticated, or ambiguous input fails closed;
- descriptors are derived; predicates and committed evidence are authoritative;
- protected proposal routes may not become protected-write authority;
- every opened veto window receives exactly one typed terminal close;
- final Gate-4 revalidation may not be separated from committed binding bytes by a client-controlled TOCTOU gap;
- audit schema changes include classification, migration, rollback, and fingerprint tests;
- public exhaustive Rust changes receive the correct semver treatment;
- never add a second audit store;
- never use real familiar declarations, personal data, or production secrets in fixtures.
True end-to-end proof necessarily crosses into OpenCoven/coven. The required
shape is:
current Threads checkout
-> pinned real Coven daemon
-> supported request boundary
-> ephemeral filesystem / coven.sqlite3 / pending state
-> scheduler, replay, restart
-> optional Cave live-daemon acceptance
Do not call gate_protected_edits directly and label the result E2E. Prove the
local Cargo override is active before running downstream tests. Use the stable
full-SHA pin for required pull-request checks and coven/main only as a
scheduled canary.
Use a GitHub issue for work that affects public contracts or crosses
repositories. Link the corresponding threads-* bead when Beads tooling is
available, but:
- clean-clone bootstrap and CI must not depend on a personal Beads database;
- do not commit local interaction logs merely to satisfy task bookkeeping;
- schemas and deterministic fixtures may be versioned; mutable operational history is not protocol source.
Phase gates matter. Phase N+1 does not silently bypass an unresolved freeze or sign-off gate.
Every authority-relevant pull request must state:
- objective, acceptance criteria, and non-goals;
- exact files and canonical contracts consulted;
- authority, privacy, compatibility, and migration impact;
- exact commands and results;
- lower-level regression evidence;
- downstream canary status or an explicit reason it is not yet runnable;
- rollback path and remaining uncertainty.
For a named Phase-5 blocker, closure requires red -> production fix -> green through the real daemon boundary as described in the E2E contract.
Under the adopted Phase-5 solo-maintainer policy, Val performs the human coherence acceptance and the subsequent scoped freeze/reaffirmation. Val may author and self-review; agent reviews are engineering evidence, not independent human approval. Agents must never simulate, self-attest, or close either human gate on Val's behalf.
- 🌿 Sage: contract synthesis, conformance mapping, evidence packets.
- 🔮 Echo: predicate, audit, replay, and substrate-authority review.
- 👑 Nova: daemon integration and technical coherence review; Val owns human acceptance.
- ⚡ Cody: Rust contracts, regressions, and deterministic test seams.
- ✨ Charm: Cave language and live-daemon human acceptance.
GitHub accountability remains with an authenticated maintainer until a familiar has independently authenticated repository authority.
OpenCoven/familiar-contract: upstream familiar identity contract.OpenCoven/coven: daemon, persistence, staging, scheduler, and apply owner.OpenCoven/coven-cave: human oversight surface; forwards, never decides.OpenCoven/coven-memory: promotion producer; Threads decides whether writes may commit.OpenCoven/psyche: orchestration consumer of authority-bound snapshots.