Git-Backed Audit — Every Handoff Is a Commit

How it works

When Forge runs your workflow, it commits each persona’s output to a workflow-scoped branch:

1
2
3
4
5
6
7
8

forge/workflow/{workflowId}/run/{runId}
├── .workflow/spec.json          ← the workflow spec (self-describing)
├── .workflow/brief.md           ← the original natural-language brief
├── .agents/alex/handoff.json   ← Alex's structured output
├── .agents/alex/handoff.md     ← Alex's freeform output
├── .agents/sam/handoff.json   ← Sam's research summary
├── .agents/sam/handoff.md
└── .agents/<other personas>/...

Every commit message includes:

• The workflow ID + run ID
• The persona’s ID
• The phase (initial run or an enrich re-run)
• An idempotency key (so re-runs don’t double-spend on LLM calls)

The persona is also recorded as a Co-authored-by line — so when you browse the commits on GitHub, you see each persona “authoring” their own handoff. The history reads like a team’s git log.

Two storage modes

Linked repo

You point the workflow at one of your own repositories. Forge commits to a workflow-scoped branch on that repo. You can git fetch the branch anytime and inspect the entire workflow’s history. Want a PR on terminal? Forge opens one against your default branch. Want to merge handoffs into your main code? It’s just git from there.

Shared repo

If you don’t link a repository, Forge creates a hidden one per organization (forge-shared-workflows-{orgId}). All your runs commit there. You browse them through the Forge dashboard; the underlying git repo is invisible to your users, but it’s still a real git repo — auditors can be granted read-only access if needed.

Either way, git is the system of record. The Forge state in our database is just a projection of what’s in git.

Why git, not a custom storage layer

Three reasons:

1. Durability. Git is bulletproof. If our service vanished tomorrow, your workflow history is still on disk in a repo.
2. Diff-able. When the management agent re-runs a persona with enrichment instructions, the new handoff is a commit. The old one is a commit. git diff shows you exactly what changed. No special diff tool needed.
3. One mental model. Engineers already know git. Auditors recognize git. No new system to learn — and no proprietary lock-in.

Use cases

• Operator review. When a workflow escalates to you, you see every previous attempt in branch history. You can compare attempts, pick the best, or commit a corrected handoff yourself — the workflow resumes from the next transition.
• Compliance audit. SOC 2, ISO 27001, HIPAA — auditors get git log access. Every persona’s input/output, every management verdict, every retry: it’s all in commit history. No special audit tooling required.
• Version history. Six months after a workflow ran, you can pull up the exact spec, brief, handoffs, and verdicts. The branch is permanent until you delete it.
• Workflow forking. Take a successful run’s branch as the starting point for a similar workflow. The spec + brief are right there.

Security

• Linked repo: Forge uses the GitHub App credentials you authorized at workflow creation. Commits use the App’s identity. Revoke the App → Forge can no longer push (and ongoing workflows escalate cleanly).
• Shared repo: per-organization isolation. Operators of org A can never see commits from org B. The repo’s owner is the GitHub organization you registered with Forge.
• Branch deletion: deleting a branch removes the SHAs from the active git tree but they remain in the reflog for the standard GitHub retention window (typically 90 days). For compliance scenarios requiring stronger guarantees, opt into archive-as-tag on workflow completion.