Find the Decisions that apply

Before you plan a change, ask by the place you work in; before you change code, ask by the files. An agent can ask both questions too. The examples use the places from Domains and Areas: the Domain DOM2 "Payments", and its Area ARE1 "Billing", which covers internal/billing/** in acme/app.

By the place you work in

Search for the Decisions in force in a place:

{"types": ["Decision"], "states": ["ratified"], "place": "ARE1"}

That is the MCP tool search. In a shell:

./smeldr-cli search --type Decision --state ratified --place DOM2

RECORD  TYPE      STATE     TITLE
D2      Decision  ratified  Payments use idempotency keys
1 of 1

A place search lists what is placed in exactly that place. Searching DOM2 does not list the Decisions of its Areas, and searching an Area does not list its Domain's. To see everything that applies to some code, ask by its files instead. --place none lists the Decisions that have no place yet.

By the files you change

Name the repository and the paths, as a person in a shell:

./smeldr-cli decisions-for-paths --repo acme/app internal/billing/invoice.go

AREA  NAME     APPROVAL           PATHS
ARE1  Billing  requires-approval  1

DECISION  PLACE              TITLE
D1        organization ORG1  Log no session tokens
D2        domain DOM2        Payments use idempotency keys
D3        area ARE1          Invoices are immutable
3 Decisions in force; 0 paths uncovered

With --stdin it reads the paths one per line, for example from git diff --name-only main | ./smeldr-cli decisions-for-paths --repo acme/app --stdin.

An agent asks the same question with the MCP tool decisions_for_paths:

{"repository": "acme/app", "paths": ["internal/billing/invoice.go", "docs/readme.md"]}

The answer has three parts:

• areas: each Area that covers one of the paths, with its approval mode, the paths it covers and the rules that put them there;
• decisions: each Decision in force placed in those Areas, in their Domains, and in the Organization, with place and place_address saying where it sits;
• uncovered: the paths no Area covers.

Only Decisions in force are listed: a proposed or superseded one is not. A path no Area covers gets no Decisions at all, not even the Organization's, so add a coverage rule for it. To leave out the Organization's Decisions, send "include_organization": false (--no-organization in the shell). One call takes up to 3,000 paths; split a longer list.

You see only what you may read: an Area or a Decision you may not read is left out, and a path that only such an Area covers reads as uncovered.

What a Decision's sources pin

A Decision can rest on a file: a specification, a readme, the code that implements it. Its sources pin each such file to one commit, so a reader can fetch exactly what the Decision was ratified against. Only files in a git repository can be pinned.

A Decision holds up to 20 sources. Set them with create_decision or update_decision while the Decision is proposed, or from a shell:

./smeldr-cli decision sources D8 --set pins.json --rev 0
./smeldr-cli decision sources D8

Once the Decision is ratified, its sources are locked with the rest of it. To pin a new commit, supersede it with a new Decision: what was ratified is the claim together with its pins. Smeldr stores the pins and never fetches the files; the reader fetches the file at the pinned commit and can compare the hash.