Spec: Audit Coverage Matrix
Mirrored from
docs/design/auditability/specs/coverage-matrix.md. Edit the source document in the repository, not this generated page.
Every Orbit operation that touches code, task state, persistent runtime state, external services, or provider/tool execution must have an audit channel. This matrix defines the expected channel by operation class.
Why This Exists
Section titled “Why This Exists”“Audit everything” is too vague to enforce in review. A coverage matrix gives reviewers a concrete checklist and makes known gaps visible.
Operation Classes
Section titled “Operation Classes”| Operation class | Required audit channel | Minimum fields |
|---|---|---|
| Top-level CLI command | Command audit row | command, subcommand, role, status, duration, cwd |
| Orbit tool mutation | Command audit row or targeted runtime row | tool/action name, target type/id, actor, status |
| Task lifecycle update | Command/tool audit plus task history | task id, actor, status transition or document field changed |
| Task lock reservation/check/release | Targeted command audit row | reservation target, files payload, status, conflict/denial state |
| Activity/job run | V2 envelope JSONL | run id, agent identity, run start/finish |
| Activity/job step | V2 envelope JSONL | run id, step id, outcome or skip/retry reason |
| Filesystem policy decision inside v2 run | V2 envelope JSONL | profile, op, path, allowed, matched rule |
| Filesystem or proc-spawn policy denial live projection | Global tracing JSONL | target, tool, path, profile, matched_rule |
| Friction task submission live projection | Global tracing JSONL | target, task_id, agent, model, summary |
| HTTP provider turn | Loop audit JSONL plus blob store | run id, session id, provider, model, request/response blob hashes |
| Tool call inside HTTP loop | Loop audit JSONL plus blob store | run id, session id, tool name, input/output blob hashes, outcome |
| CLI backend provider invocation | V2 envelope JSONL | provider, redacted argv, stdin/stdout/stderr blob refs, timeout, exit code |
| Invocation cost/usage | Invocation store | job run id, activity id, task ids, agent, model, token usage, tool-call summary |
| Audit export/prune | Command audit row (planned) | command, actor, target, status |
Invariants
Section titled “Invariants”- A mutation path must not rely only on stdout text for auditability.
- A provider request or response must not be stored inline in a command audit row.
- A policy or allowlist denial must record both the denied subject and the reason.
- Live tracing projections must be additional to canonical audit, error, log, or scoreboard writes.
- A task-state mutation must leave task history or document metadata in addition to any audit row.
- New operation classes must update this matrix in the same PR that introduces the operation.
Known Gaps
Section titled “Known Gaps”orbit auditcommands are not currently wrapped byAuditGuard, so export and prune operations are not command-audited.- Some deterministic automation actions rely on enclosing job context rather than dedicated targeted audit rows.
- CLI backend tool allowlists are recorded as harness-delegated advisories, not enforced Orbit denials.
- Command audit stdout/stderr fields exist but are not broadly populated.
Review Checklist
Section titled “Review Checklist”When reviewing a change that mutates code or state, ask:
- Which operation class does this change add or modify?
- Which audit channel records success?
- Which audit channel records failure or denial?
- Which actor or agent/model identity is persisted?
- Are payloads redacted before durable storage?
- Does the change require a new ADR because it changes the audit contract?
Agent Signature
Section titled “Agent Signature”Last revised by codex / gpt-5.5 for [T20260427-0023].