I shipped recently of an open-source architecture guard for AI coding agents

I'd keep the semantic part out of Guard for now. "This test actually verifies the intended behavior" is a much harder claim to make deterministically than "this module must not import that module." Guard can enforce structural contracts around tests, but deciding whether an assertion meaningfully covers the behavior probably needs a different layer. The interesting part is whether we can turn some of those recurring judgment calls into explicit, checkable contracts once a team has identified the pattern.

That's exactly the idea. Existing debt shouldn't make the gate useless on day one, while anything newly introduced should still be visible. Cursor is one of the integrations I'm especially interested in seeing used on real projects, so I'd be curious how it fits your workflow.

Small correction: Guard is at 0.7 now. But I’m curious about the “one real team running it” part — what would you actually want to see a team do with Guard before you’d consider it proven? A real agent workflow, CI enforcement, something else?

Yeah, baseline drift is probably a more useful signal than the raw finding count. A growing baseline can mean the team is accumulating debt, but a shrinking one shows that old violations are actually being retired. I also like the idea of tracking rules that repeatedly generate findings without getting fixed - that’s useful feedback on whether the policy is too noisy or the boundary itself needs to be reconsidered.

That’s the distinction I’m aiming for. A passing test suite tells you the observed behavior is still okay; it doesn’t necessarily tell you whether the change still fits the system. The useful part is catching that mismatch while the change is still in the agent’s workspace, when fixing the architecture is much cheaper than discovering it through production behavior.

Yes, that’s exactly the distinction provenance is meant to preserve. The run records the policy/baseline context used for the decision alongside the repository state, so a later audit can see what was actually evaluated rather than just looking at the current policy. That’s particularly useful when an agent can modify both code and the rules governing that code.

Yes, that’s exactly the distinction provenance is meant to preserve. The run records the policy/baseline context used for the decision alongside the repository state, so a later audit can see what was actually evaluated rather than just looking at the current policy. That’s particularly useful when an agent can modify both code and the rules governing that code.

Exactly. A green build mostly tells you that the behavior you tested still works. It doesn't tell you that the change respected the architecture around that behavior. That's the gap I'm interested in: checking the change against the project's existing boundaries and explicit rules, rather than asking another model to review the code and hope it notices the same architectural problem.

That's a real tradeoff in the current implementation. The fingerprint doesn't include line numbers, so reformatting or moving code around within a file shouldn't resurrect an existing finding. It does include the rule ID and file path, plus the import specifier and, where relevant, the resolved path. Contract, budget and cycle findings also use paths.
That means a mechanical file rename or module move can produce a new fingerprint and bring the finding back. That's intentional to avoid one baseline entry suppressing the same violation everywhere, but rename-heavy refactors are definitely an area where the baseline could be smarter.

Yes. That’s the kind of narrow exception the contract model is intended to express. You can scope the allowed edge to the relevant entrypoints/packages rather than opening up an entire directory. A separate rule can still reject the route-to-persistence path, so allowing payments -> credits doesn’t implicitly make routes -> persistence valid.
The important part is that the exception is part of the explicit contract, rather than something the agent can infer and broaden.

Both. The policy is stored at the repository level, but enforcement can be scoped to specific boundaries.
For example, rules can target files, contracts can use scope and entrypoints, package boundaries can use fromPackages / mustNotImportPackages, and budgets can be scoped to particular modules or routes.
The baseline is also repo-managed and fingerprint-based: it suppresses findings that already existed, while a new error finding still fails the gate. Normal checks are read-only with respect to policy; changing rules, contracts, baselines, or waivers requires an explicit CLI/MCP operation, and protected mode can prevent an agent from approving its own policy change.

Yes - that's exactly what protected approval is for. In protected mode the agent can propose a policy change but can't approve it, and with requireDistinctActor the approver has to be different from the proposer.
So code and policy can still appear in the same PR, but a green verification result doesn't make the policy change self-approved.

The distinction you draw between "was this already here" and "do we still consider this acceptable" is the right cut, and it has a consequence that is easy to miss: the second question has no stable answer, so it cannot be stored the way the first one can.

Baseline is an empirical claim about the past. A fingerprint of existing findings is either in the recorded history or it is not, and that answer does not change next month, because the past does not change. Policy is a claim about what the team currently believes, and that belief moves. When a boundary is redefined, every prior violation that the new opinion now condemns looks identical in the data to a violation that has always been wrong. Repository history can tell you it is old. It cannot tell you which opinion graded it.

That collapses into a real mechanism problem at the moment policy changes, because a single edit to a rule can reclassify hundreds of findings in one commit. If the baseline is keyed on finding identity, a boundary redefinition will look like a wave of new violations and the gate will fail on a change that only touched a rules file. That is the failure that gets gates switched off, and it arrives exactly when the architecture is being deliberately reorganised rather than incidentally broken. What the baseline needs to record is not just that a finding was pre-existing but which policy version it was pre-existing under, so that a redefinition is distinguished from a regression.

The measurement question underneath is harder than the corpus it runs on. Every finding is generated by the rules you wrote, so the boundary set the tool checks is a subset of the boundaries someone already thought to formalise. A violation of a boundary nobody has written down yet is invisible by construction, and it is the one most likely to matter, because the whole point of the post was that the change passed while making the project worse.

On the interest side, this is the second time I am commenting on this thread, so the same note applies as before: I build Piramyd, a gateway for coding agents, and a deterministic gate that keeps checks out of the context window is the direction I would argue for anyway.

When a rule is redefined, should the reclassification land as a policy diff a human approves, or should the gate keep old findings suppressed until someone consciously re-baselines?

Exactly. That's also why I keep baseline and policy separate in Guard. Baseline answers "was this already here?", while policy answers "do we still consider this acceptable?" Git history can help with the first, but it shouldn't decide the second.

Guard supports two deterministic modes. The default check can verify the full project, while check --changed limits findings to changed files. The review command is change-scoped by default and adds a bounded, redacted diff, project context, contracts, deterministic findings, and architectural impact.

So it can run after an agent finishes a task, or be used in a change-scoped workflow. Guard itself doesn't call an LLM or decide when a host should invoke it; automatic Stop/completion integration is host-specific.

I'm deliberately keeping the deterministic gate outside the LLM context path. The MCP review tool prepares a bounded packet for an external AI or human reviewer when semantic judgment is useful. Core pass/fail checks don't require a model.

Existing findings are handled through the baseline, while new error findings fail the run. Warnings remain advisory.

The gap between an error-level rule that blocks and a warning that informs is where most of these gates quietly die, and it is worth being explicit about why.

An advisory warning is a request for attention from the person who is already the most time-constrained actor in the pipeline: whoever is trying to land the change. Anything that only informs has to compete with the entire rest of the review surface, and it loses. Not because anyone decided the finding did not matter, but because there is no moment at which someone is forced to decide. The interesting property of a hard failure is not severity, it is that it creates a decision point. Without one, the disposition of every warning is decided implicitly, and the implicit answer is always "later".

That is why I would be suspicious of a rule set where the error tier is small and the warning tier is where the real architecture beliefs live. If the team would revert a change over it, it is an error. If they would not, it does not need to be a warning at all, it belongs in a report nobody is blocked by, reviewed on a schedule rather than at submission time. The useful split is not severity, it is whether a human is being asked to act at this moment or whether this is material for a conversation that happens later.

The other thing this depends on is which side of the boundary the check sits on. A gate that runs at the point where the agent finishes is enforcing a rule against a diff that already exists, which is fine, but it is the weaker position. A check that a host can invoke while the agent is still working is enforcing the same rule against a change that has not been written yet, and the cost of compliance at that point is near zero instead of being a rewrite. Same rule, same determinism, very different economics for the person on the other end of the failure.

Same disclosure as earlier in this thread, since it is now my second comment here: I build Piramyd, a gateway for coding agents.

For the warning tier specifically, do you record anywhere whether a warning was ever resolved, or does it just disappear from the report the next time it is clean?

Guard fails hard on new violations when they're covered by an error-level rule or contract. Existing findings can be baselined, while warnings stay advisory. For architecture boundaries I'd normally use error; warnings are more for cases where the result needs a human look rather than an automatic failure.

Yeah, Stop is probably the cleanest place for that kind of check. You want the agent to finish its work first, but still catch the obvious stuff before the result gets handed back. I hadn't looked closely at Muse's hooks yet, but that integration point makes a lot of sense.

Not really yet. It's still early and I'm mostly trying to get Guard in front of people actually using coding agents on real projects. The workflow change is the part I'm most interested in seeing once people start using it on larger codebases.

Yeah, I agree with this. A baseline shouldn't quietly become a permanent exception list. Having an owner, reason and some kind of expiry would make it much harder to forget why an exception exists in the first place.