Immutable Log of Build‑Intent Write Proposals for Auditable Post‑Mortem Review

Hidden risk of unrecorded decisions

When an agent decides to modify a repository, the decision often disappears before the write is attempted. The only artefact that survives is the committed file. If the write fails, the reason is lost. If the write succeeds, the intent is invisible. This gap makes post‑mortem analysis a guess. Teams cannot prove whether an agent acted within policy or over‑reached. The lack of a decision record also prevents compliance audits. Regulators expect a trace from intent to effect. Without it, you cannot answer “who authorised this change?” or “was the change approved by policy?”

The gate as the natural audit point

The Build‑Intent gate already mediates every write proposal. It validates licensing, resolves invariants, and returns a terminal state. Because the gate is the only place where an agent’s intent is examined, it is the only reliable place to capture that intent. Recording the proposal at this moment yields an immutable log that is both complete and tamper‑evident. The log entry contains the agent identifier, the proposed file paths, the diff payload, the policy context, and the gate’s verdict. It does not contain the generated code itself, only the request metadata, so storage costs stay low.

An immutable log can be implemented as an append‑only ledger backed by cryptographic hashes. Each entry is hashed together with the previous entry, forming a chain. The chain’s root hash can be published to a trusted location, such as the root‑of‑trust archive, providing external verification that the log has not been altered. When a later audit queries the log, the hash chain proves that the entry existed at the time of the write attempt.

Using the log for forensic review

Suppose a production incident is traced to a file that an agent altered. With a write‑proposal log you can retrieve the exact request that reached the gate. You compare the proposed diff with the final committed version. If the gate rejected the request, the log shows the rejection reason. If the gate accepted it, you can verify that the downstream build‑intent process applied the same artefact without further mutation.

The log also enables policy‑level analytics. By aggregating proposal metadata you can spot agents that repeatedly request changes outside their allowed scope. You can feed those statistics into the policy engine that drives the gate, tightening constraints before the next write attempt. Because the log is immutable, any statistical audit can be reproduced later for compliance reporting.

Getting started this week

1. Enable write‑proposal logging at the gate. The MCP server already intercepts agent write requests; configure it to emit a JSON record to a write‑ahead log file.
2. Wrap the log file in a simple hash‑chaining script. Append each new record, compute the cumulative hash, and write the hash to a side‑channel file.
3. Publish the latest hash to a trusted location each night – for example, the root‑of‑trust archive.

With those three steps you will have a verifiable audit trail without changing any agent code. The next time a change is questioned, you can point to the log entry and the published hash as proof of what the agent intended and what the gate allowed.

For a deeper look at how the gate enforces policy, see the pillar post on governing code agents at the Build‑Intent gate. It explains the surrounding controls that make the write‑proposal log a reliable source of truth.

Implementing an immutable write‑proposal log turns a hidden decision point into a transparent, auditable process. It reduces risk, satisfies compliance, and gives engineers a concrete tool for post‑mortem review. Start the simple logging configuration on Monday; the benefits will appear the first time you need to answer “who asked for this change?”.