Git-Native Persistence

matic uses git as its operational database, not just its version control layer. Every agent decision, execution record, artifact, and policy change lives as a file in the org's git repository, where it remains readable, diffable, and recoverable with standard tooling rather than a proprietary control plane. This section explains the concrete mechanisms behind that model: isolated worktrees for execution, append-only records for operational state, commit-level attribution for authorship, and reproducible runs pinned to specific repository state. Together, these guarantees make agent activity inspectable with the same git workflows teams already use to understand software history.

Overview

Overview explains the design rationale for treating git as the persistence layer.

Branch and Worktree Model

Branch and Worktree Model describes how each agent gets a scoped git worktree per task to enforce workspace isolation and prevent direct writes to shared branches.

Commit Attribution

Commit Attribution shows how commits are stamped with the agent handle, run ID, and timestamp that produced them so history stays attributable without extra tooling.

Immutable Records

Immutable Records covers how Decision and Run records use append-only semantics so past state can be queried but not silently altered.

PR-Based Contributions

PR-Based Contributions defines the constraint that all agent changes to shared surfaces, including policies, skills, archetypes, and project repos, go through pull requests before becoming canonical.

Run Reproducibility

Run Reproducibility explains how each Run record pins the org repo's git commit hash at execution time so past executions can be replayed against the same asset state.

Audit and Diffability

Audit and Diffability shows how append-only audit history and git-stored operational state let operators reconstruct what happened, when, and why with git log, git diff, and git blame.