Spec is the source of truth. So why is only the code guarded? - "Spec Drift".

[Sawaiz-zip]

I have been building a tool for spec drift called SpecGuard, and I would like this community's feedback on the approach. Below is the problem as I see it, what I built, and where I am still unsure. I have kept the questions for the end.

We guard the code, not the spec

Spec-driven development flips the old order: the spec is the source of truth and the code follows from it. But look at what we actually guard. Code has tests, CI, review, CODEOWNERS, branch protection, required checks. The spec, which now drives all of that, usually has none of it. A change to a spec or the constitution is a plain diff we hope someone reads, and a small doc diff rarely gets the scrutiny a code diff does.

So in an SDD repo the most important file is often the least guarded. That is backwards, and it is the gap I wanted to close.

It compounds with humans and multiple agents

One person owning the spec keeps this manageable. Several people plus several agents does not. Different agent sessions read the same spec a little differently, and a change can arrive looking completely reasonable: a PR titled "clean up the onboarding docs" that quietly adds a feature the project had ruled out. The tests stay green, because tests guard the code, not the spec's scope. Nobody decided to change direction, but it changed, and each missed change becomes the baseline for the next. That is spec drift, and it compounds.

Path-based rules do not quite catch it either. CODEOWNERS can require an approval on a file, but it cannot tell a typo from a redirection.

What I built

SpecGuard is an overlay, not a new format. Three ideas, working together:

• Identity. You lock the goal and scope once, and name who is allowed to change direction. In a Spec Kit repo it derives the goal and scope from the constitution and the touched spec, so there is nothing new to maintain.
• Meaning. On each pull request it classifies a change to a watched spec file as additive or a scope change, with a confidence score using LLM by looking at the diff and locked scope. Additive passes silently, so honest work has no friction. Only the semantic call uses a model.
• Enforcement. The strict parts use no model at all. Editing a protected file when you are not in the role that owns it is a hard block, and governance is read from the trusted base commit, so a PR cannot rewrite the rules it is judged by. A real scope change is held at the merge gate until a named role approves.

It runs as a required GitHub check, with a CLI and an MCP server that share the same verdict, so an agent can check a draft before it writes and the same decision is enforced at merge.

How it sits next to work already happening here

There is good work near this already, and this is meant to sit beside it, not on top of it. #2726, #3674, #3078 and the architecture-guard extension mostly ask "does the code match the spec." I am aiming one step earlier: "did this change move the spec's direction, and is the author

allowed to move it." That feels complementary to conformance checking rather than a replacement for it.

What I would like your feedback on

• Is governing the spec's direction, role based and at the merge gate, the right layer? Or should this live inside conformance checking instead of beside it?
• Where would it misfire for you? False positives are what kill a gate, so that is the feedback I want most.
• If you handle spec drift some other way today, what has worked and what has not?

Repo, if you want a look: https://github.com/Sawaiz-zip/spec-guard. It runs its own gate on its own specs. Thanks for reading.

[mnriem]

Sharp framing — "we guard the code, not the spec" is a real observation. One gentle reframing, then where I think this fits natively:

I'd drop the term "spec drift." In Spec Kit the spec isn't hand-edited — you (re)author it by running /speckit.specify, and it's meant to change to absorb business requirements. "Source of truth" means precedence (spec wins over code), not immutability. So a scope change isn't an anomaly to catch — it's the spec doing its job.

Separate those and what you're really guarding is authorization: who may redirect the product, and was it labeled honestly. That's a legitimate governance concern in big multi-maintainer/agent repos — just worth naming as governance, since your riskiest piece (the additive-vs-scope classifier) is exactly what will misfire against legitimate changes.

The good news: most of this plugs straight into Spec Kit rather than beside it.

• Meaning (classifier) → an after_specify extension hook. Spec Kit fires before_/after_ events for every command via .specify/extensions.yml. Running your check at after_specify catches things when the spec is authored, before a PR exists; before_converge is a natural backstop.
• Identity (goal/scope + roles) → extension config. Package it with a config-template.yml like the bundled git extension.
• Enforcement → keep the GitHub required check, paired with a /speckit.guard.check command sharing your CLI/MCP verdict.
• Ship as a bundle + list in catalog.community.json so it installs and discovers like the architecture-guard extension.

Reframed that way it's not "a guard against the spec changing" (which fights SDD) but "a governance extension routing unauthorized redirections to a named owner" — complementary to converge, riding Spec Kit's own hook machinery. The after_specify/before_specify hook contract is spelled out right in specify.md, and the git extension shows the packaging — both already in the repo as working templates.

Co-authored with the assistance of GitHub Copilot (model: Claude Opus 4.8).