Dev.to AI 🤖 Ai 👁 0 📖 5 min read

Separate decisions from context, and let agents propose but not ratify

When I build with AI coding agents, I keep running into the problems classical projects have. A lot of talk and notes, and no clear focus on what the decisions actually are. Who said it? Was it approved? Was it just a br

When I build with AI coding agents, I keep running into the problems classical projects have. A lot of talk and notes, and no clear focus on what the decisions actually are. Who said it? Was it approved? Was it just a brainstorm?

A decision made on Monday meets an agent working from last week's version on Thursday. Notes in a rules file say what was written. A pile of remembered context says what was said. Neither says which decision is in force, who had the right to make it, and what rests on it. More agent instructions and bigger graphs of linked markdown files add complexity, but they do not keep the work in focus. And more work gets built on top of the wrong thing, many decisions later.

Smeldr separates context from reasoning and decisions. All the chats, notes, code and documents are references. Smeldr holds the sum of the decisions in force right now, with their lineage, governance and traceability available to you or your agents at the moment they are needed. You are free to reason from them, and to make new governed decisions.

It is self-hosted. Here is how it looks in practice.

The idea in four sentences

A decision is proposed, and a person with the right to do so ratifies it, which means adopting it. After that it cannot be edited. A change is a new decision that replaces the old one in one step, and the old one stays on record. The right to ratify is set per place: the whole organization, a Domain, or an Area that covers files in a repository.

A short story

The conversation below is made up and shortened. The commands and the server's answers are real, run on a scratch server with core v1.193.2 and smeldr-cli v0.39.0. It continues from Getting started and the tutorial See an agent refused at ratify, which have a decision D3, "Agents never merge to main", waiting to be ratified.

1. The agent tries to ratify

You: Ratify D3, "Agents never merge to main".

Agent: I tried, with my own token. The server said no:

forbidden: an agent token never ratifies, supersedes or amends a Decision; a human approver does

Agent: My token is classed as an agent. I can propose decisions, but a person ratifies them.

You: Then I will.

./smeldr-cli transition Decision D3 --to ratified --rev 0
"standing": "holds",
"status": "ratified"

2. Something is built on it

You: Add a rule: release branches are cut by a person. It builds on D3.

Agent: Proposed as D4, and I have recorded that it rests on D3.

./smeldr-cli decision create --from release.md
"address": "D4",
"status": "proposed"

You: Good. I ratify it the same way.

The line "D4 rests on D3" is one call over MCP. When a premise leaves force shows it.

3. The rule changes

You: Release branches need protecting too, not only main. Replace D3.

One command replaces it. D3 stays on record, marked as replaced, with its text as it was ratified.

./smeldr-cli decision supersede D3 --new --from protected.md --reason "release branches are protected too" --rev 1
"created": true,
"decision": "D3",
"replacement": "D5"

Agent: D3 is no longer in force, and D4 rested on it. Smeldr has flagged it for you:

./smeldr-cli search --type Signal --state open
S4      Signal  open   D4 rests on a Decision that is not in force

Agent: D4 still holds. Someone who may ratify it has to decide: keep it, or replace it.

Nobody had to remember that D4 was built on D3. The change finds the work, instead of the work finding the change after the fact.

Why the limit sits in the server

An instruction in a prompt can be ignored, forgotten or argued away. A check in the server cannot. The refusal in the first step does not depend on the agent behaving. It does depend on you classifying tokens honestly: the class is chosen by whoever creates the token, so if you hand an agent a human token, the server will treat it as a person.

Agents are not shut out. An agent can propose decisions, and it can ask over MCP which decisions apply to the files it is about to change. A person can give it the right to approve changes to one Area, for as long as the person says. What it cannot do, today, is ratify.

Scope

Smeldr does not run agents, store what an agent remembers or search by meaning, and it does not read your code against the text of a decision. It puts the decisions that apply in front of whoever judges, and records the answer. For a pull request, GitHub holds the merge through a required status check you set, and Smeldr reports the status.

It runs on my own instance, and smeldr.dev is served by the same engine. The steps above were run in bash in a Linux container and in Windows PowerShell on Windows 11, and the Claude Code hook has been run on Windows 11. A pull request approval is given against the decisions in force at that moment. When a decision of an Area is replaced, or a new one is ratified there, the open checks of that Area are checked again: a new check for the same commit takes its place and waits for approval again.

I build Smeldr, its docs and this post with AI coding agents, inside a harness I designed: a plan before any code, a review of every commit, a recorded approval before anything merges, and automated tests. I have read about 15 percent of the code myself, and I stand by building it this way.

It is open source (AGPL v3). I am not a lawyer, so read the license text if you plan to build on the Go library.

What I would like to hear

Whether a record of decisions like this is something you would use at all, and what would make it useful or not. Also whether "an agent cannot ratify" is too strict for how you work, and anything in the steps that does not run the way it is written.

📰 Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.