Commit graph sidecar

Load and validate the commit graph that links agent SHAs, scopes, and edges.

What you will learn

• loadCommitGraph
• validateCommitGraph
• Annotate after checkpoints

Prerequisites

• Atomic commits with commit_checkpoint

Surface

What this feature does

Commit graph JSON records nodes (SHAs, subjects, scopes) and edges. validateCommitGraph catches dangling-from, key-mismatch, and missing-sha issues. Prefer annotation via governed checkpoints — not history rewrites.

How to call it

Call these MCP tools through your AGS / tower-gov host — commit_checkpoint, commit_get.. Prefer scan/get before validate/diff, and enforce only when the change set is ready.

1. loadCommitGraph
2. validateCommitGraph
3. commit_checkpoint (annotates)
4. Re-validate

import {
  loadCommitGraph,
  validateCommitGraph,
} from '@tmrxjd/agent-governance-system/commit-graph'

const graph = loadCommitGraph(process.env.GOVERNANCE_REPO_ROOT)
const result = validateCommitGraph(graph)
if (result.errors.length) console.error(result.issues)

What success looks like

validateCommitGraph returns empty errors

New checkpoint appears as node

Common failure modes

dangling-from ghost edges

key-mismatch node ids

missing-sha on commit nodes

Manual JSON edits without schema

Related reference

• API surface
• Architecture