Autonomic AI Logo
Autonomic AI
DOCUMENTATION Invariants
Architectural Specification — Core Invariants

The Engineering Invariants
That Never Fail

Our core architectural pillars replace statistical hope with deterministic mathematical and runtime constraints. By stripping away stochastic drift, autonomous software engineering becomes reproducible, verifiable, and safe for production codebases.

Architectural Invariants Pipeline

flowchart LR
    I1["01 Immutability First\n• SHA-256 Proof Sealing\n• Zero Background Mutations"] --> I2["02 Boundary Discipline\n• Fenced AST Sandbox\n• Strict Context Budgets"]
    I2 --> I3["03 Fix Root Causes\n• Zero Token Burn Loops\n• Trace Fault Pinpointing"]
    I3 --> I4["04 Zero Comment Slop\n• Pure Production Code\n• Pre-Commit AST Lints"]

    classDef invNode fill:#0d1117,stroke:#06b6d4,stroke-width:1.5px,color:#f8fafc;
    class I1,I2,I3,I4 invNode;

01. Immutability First

Fingerprint Pillar SHA-256 Proof Sealing

Once an organ or workflow step validates, all artifacts are cryptographically hashed and sealed into immutable append-only snapshots. No background modifications, uncommitted state mutations, or hidden drift are allowed.

Runtime Guarantees

  • Deterministic Checkpointing: agent-spine commits workflow step states directly to local SQLite databases with strict WAL journal mode. Steps cannot retroactively alter previously passed nodes.
  • Content Addressing: Generated test fixtures, build outputs, and code patches receive SHA-256 fingerprints recorded in .verify/artifacts/.
  • State Immutability: Functions must return fresh data copies rather than mutating shared runtime state references in-place.

02. Boundary Discipline

Fence Pillar Fenced AST Sandbox

Strict context windows and AST tool fencing. Agents cannot exceed assigned scopes, traverse unauthorized directory boundaries, or hallucinate out-of-band parameters.

Runtime Guarantees

  • Bounded Turn Context: agent-brain route_task limits injected context bundles to an exact budget (default 500 tokens), preventing context window saturation and reasoning degradation.
  • AST Parameter Fencing: All tool call arguments are strictly validated against JSON schema definitions before execution.
  • Filesystem Isolation: Tools must operate within the designated project root. Read scout guards (read_file_head, read_file_tail, file_summary) replace unconstrained full-file dumping.

03. Fix Root Causes

Troubleshoot Pillar Zero Token Burn Loops

Automatic trace analysis pinpoints logic bugs rather than looping infinite token retries and burning operational budgets on speculative guesses.

Runtime Guarantees

  • Zero Speculative Prompt Retries: When an execution fails, trace analysis and AST caller inspection isolate the underlying defect before any code patch is drafted.
  • No Defensive Null Masking: Masking root causes with defensive null-checks or swallow-catch blocks is strictly prohibited; fixes must resolve the causal logic flaw.
  • Regression Test Verification: Every defect resolution must include an isolated regression test in .verify/ that fails before the fix and passes with clean exit code 0 after the fix.

04. Zero Comment Slop

Code Blocks Pillar Pure Production Code

Enforced clean, production-grade code output without redundant assistant narrative, conversational fluff, or noisy comments in code repositories.

Runtime Guarantees

  • Pre-Commit AST Enforcement: check-added-comments.sh automatically scans git diffs and blocks commits containing AI narrative commentary (e.g. // Added by AI, // Ensure value is not null).
  • Self-Documenting Code: Types, function signatures, and expressive symbol names replace prose commentary.
  • Clean Code Diffs: Repository history remains strictly focused on functional modifications, preserving developer velocity and signal-to-noise ratio.

The Verification Proof Harness

Autonomic AI enforces that all invariant outcomes are recorded through deterministic command execution:

# Execute test suite through the verification engine
agent-brain verify -- bash .verify/run.sh

Upon completion, agent-brain generates an immutable proof record:

{
  "id": "59b0e57b-b714-49d9-a155-59ba4136b8b6",
  "exit_code": 0,
  "success": true,
  "scenario_dir_hash": "eb202b33a35e9636c6397d45677290748cc969bc60c2a6729d2bcf24e597f7d5",
  "cmd": "bash .verify/run.sh",
  "source": "cli",
  "verify_root": "/project"
}

Next Steps