Skip to content

Latest commit

 

History

History
218 lines (168 loc) · 8.86 KB

AGENTS.md

File metadata and controls

218 lines (168 loc) · 8.86 KB

coven-threads agent guide

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.

Canonical ownership

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_audit record and SQLite schema/migration contract;
  • .weave portability 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.

Normative precedence

When sources disagree, use this order:

  1. familiar-contract/rfcs/RFC-0001-familiar-contract.md for familiar identity and Ward requirements;
  2. frozen or active decision records under specs/ for Threads semantics;
  3. public Rust contracts and conformance vectors in crates/coven-threads-core;
  4. 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.

Start here

  1. Read agent/manifest.yaml.
  2. Read docs/phases.md for the honest delivery ledger.
  3. Read the relevant decision record under specs/.
  4. For boundary work, read docs/testing/e2e-contract.md and e2e/compatibility.toml.
  5. Inspect the exact public types, predicates, SQL, and tests before proposing a change.

Bootstrap and verification

bash scripts/agent-bootstrap.sh
bash scripts/agent-check.sh fast
bash scripts/agent-check.sh full

The 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 sets network_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 with bash scripts/install-gitleaks.sh "$PWD/.tooling/bin" and put that directory on PATH.

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 ci

cargo test --locked --workspace remains the compatibility source of truth. Nextest adds JUnit and flake telemetry; it does not redefine test semantics.

Automation-authority port

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_batch

The 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.

R4 change rules

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.

Cross-repository work

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.

Work tracking

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.

Completion evidence

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.

Human authority

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.

Familiar lanes

  • 🌿 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.

Related repositories

  • 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.