Documentation
Places and rights

Domains and Areas

A Decision applies somewhere. Smeldr calls that somewhere a place, and there are three kinds:

  • The Organization. Every server has one, ORG1. A Decision placed there applies everywhere.
  • A Domain, such as DOM2 "Payments": a part of the organization with its own people and its own Decisions. A new server has one Domain, "General".
  • An Area, such as ARE1 "Billing": a part of a Domain, usually the code for one piece of the product. An Area belongs to one Domain.

Places decide two things: where a Decision applies, and who may decide and approve there.

Make a Domain and an Area

A Domain belongs to the Organization, and an Area to its Domain, each by a relation. With MCP tools:

{"name": "Payments"}

That is create_domain. It answers with the address, DOM2. Then assert_relation places it:

{"source_type": "Domain", "source_id": "DOM2", "relation_kind": "belongs_to_organization",
 "target_type": "Organization", "target_id": "ORG1"}

An Area is made the same way, with create_area and belongs_to_domain:

{"name": "Billing", "approval_mode": "requires-approval"}

approval_mode is what a pull request that touches the Area needs: comment-only (the default) lists the Decisions that apply, requires-approval also waits for the Area's approver, and audit-after-merge asks for an approval after the merge instead.

Place a Decision

A Decision has exactly one place: the Organization, one Domain, or one Area. Place it with assert_relation and belongs_to_organization, belongs_to_domain or belongs_to_area. A second place is refused:

Conflict: Decision D3 already has a place (belongs_to_area ARE1): a Decision has exactly one place; withdraw that relation first

A Decision must be placed before it is ratified:

Conflict: Decision D6 has no place: place it before ratifying, with assert_relation belongs_to_domain (a Domain), belongs_to_area (an Area) or belongs_to_organization (Organization, for a Decision that spans Domains)

Where a Decision applies follows from its place. One placed in an Area applies to that Area. One placed in a Domain applies to every Area in it. One placed in the Organization applies to all of them.

A proposed Decision can be placed and moved by anyone who may write it. Once it is ratified, moving it needs the right to ratify in the place it leaves and in the place it goes to.

Who decides and who approves

Two rights follow the places:

  • Ratify, the right to make a Decision hold. An approver holds it everywhere. A domain-approver holds it in one Domain and its Areas.
  • Approve a change, the right to approve a pull request that touches an Area's files. An area-approver holds it in one Area, and a domain-approver and an approver hold it too.

A token classed as an agent can hold area-approver for one Area, when a person who holds that right gives it. It can't ratify.

approvers_of answers who holds these rights for a place you can read:

{"approvers":[{"name":"operator","role":"approver","class":"human","anchor_address":"ORG1"}],"place":"ARE1"}

administrators answers who administers the server, and any token may ask, also one that may read nothing else. From a shell: ./smeldr-cli approvers ARE1 and ./smeldr-cli administrators.

Coverage rules: which files an Area holds

An Area covers files in a repository through coverage rules. create_coverage_rule names the Area, the repository and a pattern:

{"area": "ARE1", "repository": "acme/app", "pattern": "internal/billing/**"}
  • * matches within one folder, ? one character, and ** any number of folders, as in internal/billing/**, cmd/*/main.go or **/*_test.go. A pattern without them covers one file.
  • A pattern is written from the repository's root. One that starts with / is refused, and the message shows the form to use.
  • One Area can cover files in several repositories.
  • A rule belongs to its Area permanently: to move it, archive it and make a new one.

The approval mode, the Area itself and its rules are the Area's gate, so changing or removing them needs the right to ratify in that Area. Adding a rule needs the right to approve changes there.

Smeldr never reads your repository: whoever asks which Decisions apply sends the paths. Find the Decisions that apply shows how.