Skip to content

AGENTS.md

Latest commit

 

History

History
114 lines (101 loc) · 7.93 KB

AGENTS.md

File metadata and controls

114 lines (101 loc) · 7.93 KB
Raw

Agent instructions

Zavet knowledge layer (this repo records decisions in .zavet/)

This block is generated by zavet agents-md; edit .zavet/RULES.md and the records themselves, never this text. On Claude Code and Grok Build the same content arrives live at session start — if you are on one of those, this is a duplicate, not a second and conflicting instruction.

Standing rules

Curated directives distilled from decisions. Every line here is injected into agent context at session start — keep it short and non-negotiable.

  • Never hand-edit generated contract artifacts (contract/*.schema.json, contract/testdata/signing-vector.json) — run just contract.
  • Never bump [workspace.package].version by hand — releases are semantic-release's job.
  • Every commit uses a conventional type(scope): subject with a mandatory scope, and is DCO signed off (-s).
  • Nothing content-bearing (prompts, diffs, bodies, messages) may cross the attestation wire — metadata only. See D-0001.
  • Never open an installed binary for writing — stage beside it and rename onto it (on Windows: rename the running exe aside first), or you get ETXTBSY in production and green tests. See D-0003.
  • Linux artifacts are static musl; macOS is one universal binary; Windows is two MSVC zip legs. Never add an arch branch on Darwin, a libc probe, or a Windows case to install.sh — Windows installs go through install.ps1. See D-0002/D-0010.
  • Never create the Windows control pipe without its explicit security descriptor (user-only DACL + medium integrity label) — in bind and in the accept loop, or connection #2 silently loses it. Never report ERROR_ACCESS_DENIED as "daemon not running". See D-0016.
  • dira doctor diagnoses and never acts: no --fix, and a check whose inputs are missing reports skip, never fail. Exit codes 0/1/2 are a contract. See DIRASH-0022.
  • The capture probe's session id is minted by the daemon under the reserved dira-probe- prefix and admitted only while its arm is live; every Store read filters that prefix, and the daemon never spawns the hook child — a child it forked would inherit an elevated token and certify the very bug the probe exists to catch. See DIRASH-0023.
  • dira onboard steps never abort the run (StepOutcome, not ?), and its detection pass never writes or spawns anything that writes — --print must leave the filesystem byte-identical. See DIRASH-0029.
  • Knowledge-content consent is asked by its own prompt naming what it sends, never implied by device linking or billing. Changing what full transmits changes KNOWLEDGE_DISCLOSURE in the same commit. See DIRASH-0030.
  • One backoff ladder: dira_core::sync::Backoff. Never re-add a local seed/double/cap; attempt budgets stay with the caller. See DIRASH-0031.
  • A record's first_commit/created_at/source_session are repaired as a unit and only ever earlier, with attribution read from the artifacts row for the introducing commit — never from the session doing the repair. See DIRASH-0032.
  • Nothing enters repo_dirs unless the directory demonstrably belongs to the repo it is filed under, and register_repo_dir stays I/O-free. See DIRASH-0027.

Recorded decisions (read the file before changing guarded code; ask /zavet:why)

  • D-0001 — The attestation wire is content-free; knowledge sync needs its own channel (active)
  • D-0002 — Linux ships static musl only; macOS ships one universal binary (superseded)
  • D-0003 — Replace running binaries by rename only, never by opening the target (active)
  • D-0004 — The installer and updater refuse to overwrite a development install (active)
  • D-0005 — Prerelease binaries build on manual dispatch only, while the repo is private (superseded)
  • D-0006 — The update check never performs network I/O on the foreground path (active)
  • D-0007 — The landing site vendors the installers byte-for-byte; it does not proxy them (active)
  • D-0008 — The control socket is anchored to a fixed per-user path, never $TMPDIR (active)
  • D-0009 — The control socket binds first and is the single-instance guard (active)
  • D-0010 — Native Windows targets are added to the release matrix and install.ps1 ships alongside install.sh (superseded)
  • D-0011 — TLS trust anchors ship inside the binary, never the host trust store (active)
  • D-0012 — PR-triggered CI runs on GitHub-hosted runners only, never the self-hosted pool (active)
  • D-0013 — Prerelease tags build binaries automatically now that the repo is public (active)
  • D-0014 — Windows arm64 builds on a native runner and gets its own smoke leg (active)
  • D-0015 — The release pipeline runs entirely on GitHub-hosted runners (active)
  • D-0016 — The windows control pipe carries an explicit user-only ACL and a medium integrity label (active)
  • D-0017 — Every spec counts toward coverage; verified is review, not documentation (active)
  • D-0018 — Token usage rides its own rowid cursor, never the event at window (active)
  • D-0019 — A replacement daemon is never started until the previous process is confirmed exited (active)
  • D-0020 — Sync watermarks advance per acked chunk, and a long drain paces itself (active)
  • D-0021 — Tests that exec the real binary serialise staging against forks and isolate every user dir (active)
  • DIRASH-0022 — dira doctor reports and never repairs, and absent evidence is a skip (active)
  • DIRASH-0023 — The capture probe rides a daemon-minted reserved session prefix, and the daemon never spawns the child (active)
  • DIRASH-0024 — Repo-scope zavet writes are gated on cwd, and dira never sets core.hooksPath (active)
  • DIRASH-0025 — Token attribution resolves per turn, and never writes NULL when a fallback exists (active)
  • DIRASH-0026 — Branch presence is a display state on the zavet list views, never a deletion (active)
  • DIRASH-0027 — zavet sync registers the repo and reuses the ordinary sweep, never forcing a re-read (active)
  • DIRASH-0028 — Knowledge reindex is an explicit path-scoped command, never the ambient poll (active)
  • DIRASH-0029 — Onboarding is one re-runnable waterfall, and the installer prompts only where a tty exists (active)
  • DIRASH-0030 — Full-content knowledge sync is opted into by its own prompt, never implied by linking (active)
  • DIRASH-0031 — One backoff ladder lives in dira_core; callers own their attempt budget (active)
  • DIRASH-0032 — A record's first-sight triple is repaired as a unit, from recorded facts (active)

Living specs (.zavet/specs/ — keep current while you work)

  • attestation-sync — Attestation sync and session rollups (session, high)
  • capture-pipeline — Zavet capture pipeline (session, high)
  • daemon-lifecycle — Daemon startup and ingress lifecycle (session, high)
  • distribution-and-update — Distribution and self-update (session, high)
  • doctor — Diagnostics — dira doctor and the capture probe (session, high)
  • harness-sources — Harness sources and hook ingestion (session, high)
  • knowledge-sync — Knowledge sync — the consent-gated second channel (session, medium)
  • onboarding — Onboarding — dira onboard and the installer handoff (session, high)

Capture bar: record non-obvious choices a future reader could not reconstruct — micro-decisions as commit trailers (Why:/Rejected:/Constraint:/Refs:), structural ones via /zavet:decide. Spec maintenance (do this as part of normal work, no command needed): when implementing or changing a feature, update its covering spec in .zavet/specs/ — or create one from .zavet/.spec-template.md (origin: session) for substantial new features — reference the decisions involved, and add a Spec: <slug> trailer to the commit.

Guards are not enforced by every harness

Before you edit a file, run .zavet/bin/zavet match <path> (repo-relative). If it prints decision ids, open each record and honor it — or supersede it explicitly via /zavet:decide. Never work around a guard by re-wording the change.