How a Decision moves
A Decision is a rule your organization has adopted. It stays in force until it is replaced, and it carries who adopted it, when, why, and what it rests on. This page shows the path a Decision takes, who may move it at each step, and what Smeldr does on its own.
The path
- Proposed. Anyone who may write can propose a Decision, a person or an agent. Smeldr then asks for it to be ratified: a request goes to whoever may ratify, saying the Decision waits for ratification.
- Placed. This is a step, not a state. A Decision applies somewhere: the whole organization, a Domain or an Area. It needs its place before it can be ratified, and it has exactly one. See Domains and Areas.
- Ratified. Someone with the right to ratify adopts it, and it holds. Its text is locked from then on: an edit is refused.
- Pending re-evaluation. A ratified Decision can be put up for review again. It still holds while it waits. Then it is either ratified again or replaced.
- Superseded. A change is a new Decision that replaces the old one, in one act: either the new Decision is written with it and ratified in the same step, or an existing ratified Decision is named as the replacement. The old Decision stays on record, marked as replaced, with its text as it was ratified, and its record names what replaced it and why.
- Retired. A Decision that no longer applies, with nothing to replace it, is retired. It leaves force and stays on record, with its text and the reason.
- Archived. A proposal nobody wants is archived, and so is a superseded or retired Decision that no longer needs to be in view.
Who may do what
| What | Who |
|---|---|
| Propose a Decision, and place a proposal | anyone who may write, a person or an agent |
| Archive a proposal | anyone who may manage items |
| Ratify, replace, retire, or move a Decision that holds | a person who holds the right to ratify in its place |
| Approve a code change against the Decisions in force | someone who holds the right to approve changes in that Area |
| Grant roles | an administrator |
The right to ratify comes with a role:
- an approver may ratify everywhere;
- a domain-approver may ratify in one Domain and its Areas;
- the right to approve a code change is held by an approver, a domain-approver, and an area-approver, who holds it for one Area.
An administrator manages the server, but is not an approver: an administrator who holds no approval role cannot ratify. An agent or a job can't ratify, replace, retire or amend a Decision, whatever roles it holds. An agent can approve code changes in one Area when a person who holds that right gives it to the agent.
An approver acts over MCP or with smeldr-cli: smeldr-cli transition ratifies a Decision, smeldr-cli decision supersede replaces one, smeldr-cli decision retire takes one out of force, and smeldr-cli check answer approves or declines a code change for one Area.
Moving a Decision to superseded without naming what replaced it still goes through, but the server answers with a warning and points to what to do: name the replacement, or retire the Decision. smeldr-cli decision repair repairs a Decision superseded that way: it names the replacement after the fact, or retires it.
Handing a right on
A person can delegate a right to someone else for one item, for a limited time: 14 days unless they say otherwise, and at most 90. After that it stops working by itself. The person who handed it on can withdraw it sooner.
- You can only hand on what you hold yourself, for that item. A delegation of a right you do not hold is refused.
- A delegation covers exactly one item. A role that would reach further, such as approver, cannot be delegated.
- An agent cannot receive the right to ratify, not even for one item.
What Smeldr does by itself
- Asks for ratification as soon as a Decision is proposed, and closes the request when it is ratified.
- Flags a premise. When a Decision that another rests on leaves force (superseded or retired), the one resting on it is flagged for whoever may ratify it. See When a premise leaves force.
- Puts the Decisions that cover the files a pull request touches in front of the person who approves it. Smeldr does not read the code against their text. Each Area chooses what is asked: a comment only, approval before the merge (GitHub holds the merge, through a required status check), or approval after it.
- Records every move in the item's history: who did it, what kind of actor they were, when, and the reason when one was given.
- Refuses a write made on a stale read. A ratification names the version the person read. If the Decision changed in between, the write is refused, so nobody ratifies a text they have not seen.