g what the agent read, which tools were called, what changed, which policy allowed it, and whether the session is replayable.

• Deterministic Policy Merge: A fixed 4-layer precedence model eliminates ad-hoc policy ambiguity, replacing subjective "I think the policy was" with inspectable, version-controlled TOML/JSON merges.
• Runtime Reproducibility: Shipping as a single compiled Rust binary eliminates plugin/runtime drift, ensuring identical behavior across developer laptops, CI runners, and hardened SSH hosts.

Core Solution

Akmon is a single Rust binary that functions as an AI coding agent (interactive TUI + headless --task mode) engineered for environments where reasoning, tool calls, and file changes must be independently reviewable. Every session writes 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 support deterministic replay, diff comparison, pre-review redaction, and export as portable AGEF (Agent Governance Evidence Format) bundles.

Architecture Decisions:

• Single Binary Runtime: Explicit runtime state prevents host mismatch. Troubleshooting isolates to policy, providers, repository state, or model behavior.
• Deterministic Policy Merge: Four fixed precedence layers ensure predictable rule resolution:
  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. Higher precedence rules override lower ones deterministically.
• Open Evidence Format (AGEF): The tar.zst bundle contains manifest.json, an events.bin stream of length-delimited canonical CBOR records, and content-addressed objects/<hex> files. Spec v0.1.1 is governed independently to outlive any single implementation.

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. Treating Logs as Evidence: Flat logs lack integrity guarantees and reviewer-focused structure. Evidence requires tamper-evident chains, explicit parent-child linkage, and offline verifiability. Always validate against the 5 core auditor questions.
2. Ignoring Causal Chain Linkage: Unordered event streams cannot prove that a specific file change resulted from a specific tool call and model response. Without parent linkage, audit trails are legally and technically inadmissible in regulated workflows.
3. Assuming Host Runtime Equivalence: Plugin-based or interpreted runtimes drift across environments. A single compiled binary ensures behavioral reproducibility. Never rely on host-specific dependencies for compliance-critical tooling.
4. Relying on Implicit Policy Resolution: Ad-hoc or undocumented policy overrides create audit gaps. Policy must be deterministically merged, inspectable, and version-controlled. Use akmon policy show-effective to capture the exact merged configuration before execution.
5. Expecting Model Behavior Guarantees: Governance tools do not prevent model hallucinations or misbehavior. They bound, observe, and prove consequences. Design workflows assuming unpredictable model actions and rely on the audit chain for post-hoc validation and regression detection.
6. Overlooking Offline Portability: Audit bundles must travel independently of the source repository. Relying on live dashboards, network-dependent verifiers, or repo-linked logs fails during external reviews or air-gapped audits. Always export and validate AGEF bundles in isolated environments.

Deliverables

📘 Akmon Trust Pipeline Blueprint A step-by-step implementation guide for integrating Akmon into regulated CI/CD workflows. Covers binary deployment, headless task execution, audit/evidence verification, SLO enforcement, regression trending, and AGEF bundle export. Includes architecture diagrams for policy merge precedence and content-addressed journal storage.

✅ Regulated AI Agent Adoption Checklist

• Install single Rust binary and verify runtime reproducibility across target environments
• Execute headless task and capture JSON output + session ID
• Run akmon audit verify to confirm tamper-evident chain integrity
• Run akmon evidence verify to validate schema and chain linkage
• Execute akmon slo verify --strict for single-run compliance gating
• Configure --baseline-dir and run akmon slo trend for regression detection
• Export AGEF bundle and validate offline using independent verifier
• Document effective policy merge using akmon policy show-effective
• Integrate 5-command pipeline exit codes into CI gate configuration

⚙️ Configuration Templates

• .akmon/policy.toml (project-local override template)
• .akmon/policy-packs/org.toml & team.toml (layered precedence examples)
• manifest.json & events.bin structure reference for AGEF v0.1.1 offline verification