CodcompassCodcompass
Back to KB
Difficulty
Intermediate
Read Time
4 min

Run a small headless task in your project.

By Codcompass Team··4 min read

Run a small headless task in your project.

Current Situation Analysis

AI coding agents generate functional diffs but fail to produce verifiable evidence. In regulated engineering environments (avionics DO-178C/DO-330, medical IEC 62304, automotive ISO 26262/ASPICE, industrial IEC 61508, defense CMMC, SOC 2), code without an auditable trail is a compliance liability. Auditors require autonomous answers to five critical questions: what the agent read, which tools were called with what inputs, what changed on disk, which policy decision permitted each side effect, and whether the session can be deterministically replayed.

Traditional approaches fail because they treat logging as a substitute for evidence. Logs are developer-centric artifacts optimized for debugging, not reviewer-centric artifacts optimized for compliance. They lack integrity guarantees, omit parent-child event linkage, and cannot establish causality between model responses, tool invocations, and filesystem mutations. Furthermore, ad-hoc shell scripts or flat log exports cannot travel across environments, verify offline, or gate cleanly in CI pipelines. The result is a fragile infrastructure that collapses under audit scrutiny.

WOW Moment: Key Findings

ApproachAudit Trail CompletenessEvent Linkage & ReplayabilityCI/Offline Verification Time
Traditional Agent + Flat LogsLow (mutable, dev-focused, missing policy/tool context)None (sequential only, no parent-child causality)Manual/High Effort (requires original environment & custom scripts)
Akmon (AGEF v0.1)High (tamper-evident, content-addressed, policy-bound)Full (ordered parent-child chain, deterministic replay)<5 mins (5 exit codes, zero-dependency verifier, portable tar.zst bundle)

Key Findings:

  • Content-addressed journaling eliminates mutable log drift and guarantees artifact integrity.
  • Deterministic policy merging reduces ambiguous governance tickets to inspectable, version-controlled TOML/JSON outputs.
  • Offline-verifiable AGEF bundles decouple audit review from the original development environment, enabling external compliance validation without toolchain dependencies.

Core Solution

Akmon is a single Rust binary engineered for environments where AI reasoning, tool calls, and file changes must be cryptographically reviewable. It operates in interactive TUI or headless --task mode, writing a tamper-evident, content-addressed audit chain to .akmon/audit/<session-id>.jsonl and a structured evidence summary to .akmon/evidence/<session-id>.json. Sessions are deterministically replayable, diff-comparable, redactable, and exportable as portable AGEF bundles.

Architecture & Runtime:

  • Sing

le explicit binary eliminates plugin runtime drift and host environment mismatches.

  • Reproducible across laptops, CI runners, hardened SSH hosts, and air-gapped networks.
  • Supports Anthropic, OpenAI, OpenRouter, Groq, Azure OpenAI, Bedrock, OpenAI-compatible endpoints, and Ollama. Operator-controlled model selection with no hosted runtime.

Policy Engine (Deterministic Merge): Policy resolves through four fixed precedence layers:

  1. Built-in profile (dev, staging, prod)
  2. Policy packs (.akmon/policy-packs/*.toml|json)
  3. Project-local policy (.akmon/policy.toml|json)
  4. CLI override (--policy-override) List fields append and deduplicate, preserving last-occurrence order. Effective policy is inspectable before execution.

Open Evidence Format (AGEF): AGEF (Agent Governance Evidence Format) is an open spec (v0.1.1, wire 0.1) enabling portable, offline verification. Bundles are tar.zst archives containing:

  • manifest.json (session metadata, policy snapshot, model/provider config)
  • events.bin (length-delimited canonical CBOR event stream)
  • objects/<hex>/ (content-addressed artifacts)

Implementation Pipeline:

# Run a small headless task in your project.
cd your-project
akmon --yes --output json --task "summarize failing tests and propose minimal fixes" | tee run.json

# Verify the tamper-evident audit chain for the session.
akmon audit verify .akmon/audit/<session-id>.jsonl

# Verify the evidence schema and the linkage to the audit chain.
akmon evidence verify .akmon/evidence/<session-id>.json

# Enforce a single-run SLO check.
akmon slo verify .akmon/evidence/<session-id>.json --strict

# Detect regressions vs a historical baseline.
akmon slo trend .akmon/evidence/<session-id>.json \
  --baseline-dir .akmon/evidence/history \
  --window 20 \
  --strict

akmon policy show-effective --profile prod \
  --policy-pack .akmon/policy-packs/org.toml \
  --policy-pack .akmon/policy-packs/team.toml

Pitfall Guide

  1. Confusing Logs with Evidence: Logs are mutable developer artifacts. Evidence must be reviewer-centric, tamper-evident, and autonomously answer the five audit questions without human reconstruction.
  2. Ignoring Event Chain Linkage: Flat logs cannot establish causality. You must maintain ordered, parent-linked event chains to trace filesystem mutations back to specific tool calls and model responses.
  3. Relying on Plugin Runtimes or Hosted SaaS: Runtime drift and environment mismatches break reproducibility. Use a single, explicit binary to guarantee identical behavior across laptops, CI runners, and air-gapped hosts.
  4. Ad-Hoc Policy Management: Policy must be deterministic. Use the 4-layer merge strategy (profile → packs → local → CLI) and always verify the effective policy before execution to eliminate ambiguous governance tickets.
  5. Expecting AI Governance to Prevent Misbehavior: Governance does not guarantee model correctness. It bounds, observes, and proves the consequences of model behavior, enabling controlled rollback, audit, and compliance reporting.
  6. Overlooking Offline Bundle Verification: Audit trails must travel. Ensure your evidence format (e.g., AGEF) can be verified by external reviewers without requiring the original toolchain, repository access, or network connectivity.

Deliverables

  • Blueprint: Akmon Architecture & AGEF Spec. Covers single-binary runtime design, content-addressed journal substrate, CBOR event stream serialization, policy merge algorithm, and tar.zst bundle structure (manifest.json, events.bin, objects/<hex>/).
  • Checklist: 5-Command Trust Pipeline & Compliance Validation. Includes task execution, audit chain verification, evidence schema validation, SLO enforcement, regression trending, policy inspection, and offline reviewer bundle verification steps.
  • Configuration Templates:
    • Policy TOML/JSON structure (profile definitions, pack inheritance, local overrides, CLI flag mapping)
    • AGEF Bundle Manifest schema (session metadata, provider/model config, policy snapshot, artifact checksums, event stream pointers)
    • CI gate integration examples (exit code routing, baseline directory setup, strict SLO enforcement)