ADP · the agent-native forge Spec 0.7.0 · MIT

Agents write the code. Someone still has to answer for it.

ADP is a self-hosted, GitHub-compatible forge for AI coding agents. Keep using git, gh and your existing CI, while ADP binds every change to its intent, agent provenance, approvals and signed verification evidence — and refuses to land changes that do not meet your requirements.

An agent saying “tests pass” is not proof. ADP converts that belief into evidence, and keeps the four answers production asks of every change: what was it for, what produced it, how was it verified, and can it be reversed without losing the reasoning — per change, in any harness, years later.

Plan Design Build Test Deploy Maintain
One intent · any agent — the record assembles as it works
The gate — policy reads the record
Main — every change attested
reverted
change ch_413 · signed
intentissue #413 ✓
diff+61 −18 ✓
provenancecodex · s_45 ✓
evidenceDSSE 412/412 ✓
refused · 422 gates_green unmet landed · attested Operation log — append-only, same transaction
op_0117 land ch_411 · evidence e_968 (DSSE) · signed · claude-code
op_0118 refuse ch_412 · unmet: gates_green — on the record
op_0119 land ch_412 · evidence e_970 (DSSE) · signed · claude-code
op_0120 undo op_0119 · main → 4c1e77a · reasoning kept — the log only grows
op_0121 land ch_413 · evidence e_971 (DSSE) · signed · codex
Try the moves —

MIT · self-hosted · TypeScript · PostgreSQL · the real git binary

01The lifecycle

The AI-native SDLC, enforced

The published playbooks for agentic development converge on the same shape: six stages, each ending by committing an artifact the next stage reads — the intent, the spec, the plan, the diff, the review findings, the incident record. That discipline is right, and it is held together by convention, inside the same tool that wrote the code. A convention does not bind automation. ADP is the layer where the chain becomes a constraint: typed, signed, and checked where changes are admitted.

the incident record becomes the next intent — the loop closes STAGE 01 Plan STAGE 02 Design STAGE 03 Build STAGE 04 Test STAGE 05 Deploy STAGE 06 Maintain intent spec plan + diff evidence approval incident record ADP — EVERY ARTIFACT, BOUND AND ENFORCED ON THE CHANGE every binding written to the append-only operation log, in the same transaction as the change
The loop is the playbooks' — their stages, their artifacts. The band is ADP. The full drawing, and what actually holds each artifact today, stage by stage: the AI-native SDLC, and the layer under it.
The stage commitsADP binds it as
An intent, written down before the work A typed intent the change record references, resolved from an ordinary git push
The spec and the plan that followed it Artifacts carried on the change, versioned with it rather than beside it
The diff Ordinary git objects — git clone keeps working
The review findings Gate results, each linked to a signed evidence bundle bound to the state that ships
The approval A land policy — instance ∧ organization ∧ repository — that no agent can bypass
The incident record An operation-log entry with guarded undo, written in the same transaction as the change
02Adoption

Your repository does not move

Companion mode. Your issues, branches, pull requests and Actions stay exactly where they are, and ADP fills its record as you work — no migration, no second place to look, and nothing about the day changes. The loop below is on GitHub, and none of it is an ADP command.

# your usual loop, on github.com, unchanged
gh issue create --title "Rate limiter drops bursts"
git switch -c fix/rate-limiter
git push origin fix/rate-limiter
gh pr create --fill  # your Actions run on GitHub's runners, as before
gh pr merge --squash
IntentThe issue you filed becomes the goal on the recordBy number and title, bound to the commits that answer it — a commit trailer naming #41 resolves to the GitHub issue, because that is the only number you have ever seen.
ProposalYour pull request becomes a proposalCarrying its upstream number, so gh pr view 482 means one thing on both planes. Reviews and approvals come with it.
EvidenceYour Actions results become signed attestationsGitHub's runners keep executing the workflows you already have. ADP does not run them; it records what they said, as DSSE envelopes bound to the commit.
ProvenanceWho and what produced itThe author, the harness, the session — and the model observed in the trajectory rather than the one a token claimed.
MergeThe merge is a real operation, so it can be taken backMerging on GitHub writes the operation adp undo resolves, so the one verb you most want after a bad change works on a merge ADP never performed.
Recorded without being asked. The developer above ran no ADP command, and the record is complete enough to answer what the change was for, what produced it, how it was verified, and how to reverse it.

And two checks appear on the pull request

Where the work already is, rather than in a console somebody has to remember to open.

ADP / change record

The intent, the producer, the trajectory and the evidence, linked. Never a verdict — it reports what ADP knows and never blocks a merge. A commit bound to no intent says so, rather than leaving the line out.

ADP / policy

The land verdict, with the unmet requirement and the command that satisfies it. Require it in branch protection and GitHub will not merge until ADP agrees.

GitHub stays the merge authority. Publishing a verdict GitHub already knows how to require is the same enforcement with none of the migration — so ADP refuses to merge an ingested pull request itself, and says why. Choosing between two merge planes is the thing companion mode exists to avoid.

Nothing to migrate

The repository stays on GitHub. Its issues, pull requests, reviews and Actions results are ingested; ADP's verdict is published back as a check. Point it at a repository you already have.

Runs on a laptop

Inbound arrives by polling as well as by webhook, so an instance nothing on the internet can reach still fills its record. No public hostname, no port to open.

Compatible where it counts

Validated in CI against the real, unmodified gh binary — not a mock, and not a claim of full parity.

03The record

Every change carries its proof

Git records what changed and discards why and whether anyone checked. ADP records a change as a signed transaction, and the merge is gated on it.

The change intent diff provenance Gates run isolated container, network denied ADP attests, never executes Signed evidence DSSE bundle bound to the change, not to a branch name Policy decides instance ∧ org ∧ repo land or refuse every step written to the append-only operation log, in the same transaction as the change
Requirements are additive and fail closed: an instance floor, an organization floor, and the repository's own adp.yaml. A change that cannot show the evidence does not land — and the refusal is recorded too.

Where that sits

Two planes over one domain model, with the gate between them. Above it, tools that cannot tell ADP from GitHub; below it, your runner, your delivery stack, and the repository you did not move.

YOUR AGENTS AND TOOLS — UNMODIFIED git · gh · Octokit and CI libraries · any coding agent, over the same protocols or MCP git wire · REST /api/v3 · GraphQL /api/adp · MCP ADP — THE AGENT-NATIVE FORGE, SELF-HOSTED Compatibility plane GitHub's protocols over the same domain model — an unmodified tool cannot tell Native plane operation log · undo · evidence bundles · workspaces · candidate sets · sessions the gate: land policy — signed evidence required, or the merge is refused GATE RUNNER — YOUR CHECKS isolated container, network denied; reports signed results YOUR DELIVERY + OBSERVABILITY consumes the record: identify, attribute, reverse GITHUB — COMPANION MODE issues, pulls, reviews, Actions in; two checks published back
Nothing above ADP changes and nothing below it is replaced: tools speak the protocols they already speak, gates execute on your infrastructure, and companion mode means adopting ADP is not a migration.
04After it lands

The record outlives the session

Verification is the bottleneck — and it is not the finish line. Past review sit deployment and operations, and that is where the failures are. Machine-written code passes review looking better than the code a human wrote — and introduces roughly 1.7× more critical runtime issues once it ships. Four in five teams surveyed had suffered a major production failure caused by AI code in the previous six months, and one of the four leading causes was the audit trail itself going missing.

ADP does not deploy your software and does not watch your metrics. It makes the change that broke production identifiable, attributable and reversible — because the record was written in the same transaction as the change, rather than reconstructed afterwards from a session transcript that no longer exists.

Which change did this?

An append-only operation log, written in the same database transaction as the change it describes — so there is no state in which the change landed and the record of it did not.

Produced by what?

The intent, the harness, the model and the session are fields on the change record, not a transcript inside a tool you may no longer run.

Reverse it, keep the reasoning

Checkpoints and guarded undo are first-class operations, and the rollback goes on the record the same way the change did.

And the record is portable, whichever agent wrote it. Every harness ships its own checkpoints, session store and memory files; run three and you hold three incomplete audit trails, none of which the next harness can read, and none of which outlives the vendor that wrote it. ADP records the intent, the harness, the model and the session on the change itself, in a published, versioned, MIT-licensed wire format — so work started in one agent can be reviewed, reverted or continued in another, and an auditor gets one answer instead of three. The precedent is OpenTelemetry: its win was not making tools talk to each other but standardising the record, so any backend could read all of them. Version control is one layer below, with the same problem and no such standard yet.

That is built, not planned, and make demo ends on it: one task is started under Claude Code, stops mid-work, and is picked up by Codex — one continuous signed history, with nothing calling checkpoint or resume by hand. The recording happens out of band, by reading the event stream each harness already writes, so it costs the agent nothing and needs no cooperation from the vendor: a reader is about two hundred lines, and harness stays a string the server never branches on. One command per harness connects a repository — adp connect claude-code — and then proves it worked by opening and closing a real session.

The harness should compete

Planning, context, model quality, when to fan out — that is where a coding agent earns its place, and where vendors should compete furiously.

The substrate should not

Workspaces, history, the operation log, the evidence graph, signed identity. No harness should be able to compete on owning your history.

Production-failure figures: New Relic, The 2026 State of AI Coding Report — Hanover Research, 200 US technology decision-makers, June 2026.

05What that buys you

What that buys you

Instead ofYou get
A transcript in one vendor's format, gone when the session ends Intent, harness, model and session recorded on the change itself
CI output that scrolls away A signed attestation bound to the change, verifiable later by anyone
An agent that decides for itself when the work is done Merge-time requirements the agent cannot satisfy by editing its own tests
“Who changed this, and did anyone check?” An append-only operation log, written in the same transaction as the change
A rollback that loses the reasoning Checkpoints, sessions, workspaces and guarded undo as first-class operations
06Status

Working today

CapabilityState
Git smart-HTTP, REST and GraphQL compat, driven by unmodified gh in CIShipped
Companion mode — GitHub issues, pull requests, reviews and merges ingested, with no ADP command runShipped
ADP / change record and ADP / policy published as check runs on the pull requestShipped
GitHub App created from a manifest the instance serves — no personal access tokenShipped
Inbound by polling as well as webhook, so an instance needs no public hostnameShipped
adp undo reaches a merge that happened on GitHubShipped
Signed change records, DSSE evidence bundles, SBOM per landed changeShipped
Three-level land policy, push protection, dependency admissionShipped
Operation log with guarded undo; sessions, checkpoints, workspaces, candidate setsShipped
Native plane over REST and MCP; read-only supervision UIShipped
Organizations: isolation, quotas, policy console, audit export, OIDC loginShipped
Gate runner — isolated container, network denied, no host mountsShipped
Trajectory recording out of band — hash-chained, from the stream the harness already writesShipped
One task across two harnesses as one continuous signed historyShipped
One-command harness connect — Claude Code, Codex, Gemini CLIShipped
The CLI on npm — npx @deduva/adpShipped
adp reimplement — do a landed change again, and compare the two attemptsShipped
A repository's record moves between instances with its signatures unchangedShipped
Self-hosting: Helm chart and Docker ComposeShipped
Dependency admission beyond npmPartial — npm only
SCIM provisioningNot built

The wire contract is published and versioned, served as ADP-API-Version on every response, with the spec, the image and the git tag moving together. See what a version bump promises.

07Try it

Try it

One command starts a throwaway ADP against an ephemeral PostgreSQL, then uses ordinary git and an unmodified gh to clone, push, propose, gate and land a change — narrating each step. It ends where the point is: the merge is refused while the change has no gate result and no approval, and allowed once it does. Then you read the signed evidence bundle and the operation log that record why.

git clone https://github.com/DeDuva/adp.git && cd adp
make demo

Needs Docker and Node 22. Nothing is installed, no account is created, and it all tears down when you press Enter. About a minute, most of it the first npm ci.

Run your own instance

Helm chart or Docker Compose, with the sharp edges written down — self-hosting guide.

Read the argument

Why verification became the bottleneck, and what the record has to carry once it isn't — Why ADP exists, or the six SDLC stages one by one.

Build against it

The contract is published as OpenAPI, with a conformance suite — spec/.