A nuance is one statement about what your data means, such as a boolean that marks a finance reversal rather than a loss. A detector, an agent or a person could already propose one. Nothing could answer one, so the whole layer was a notebook.
Two endpoints answer them. POST /semantics/nuances/{entry_id}/confirm takes a
required reason and an explicit set of scopes, which is what the confirmation
binds. The scopes are the confirmer’s decision rather than the proposer’s, and
an empty set is a real answer meaning the statement is true and gates nothing.
POST /semantics/nuances/{entry_id}/decline takes a required reason and binds
nothing. Declining is not deleting: it mints a retired version carrying the
reason, so a decision that was made stays readable. Both return the new entry
at the next version, and the proposal it answers becomes superseded rather than
disappearing.
Only a person confirms. Both endpoints require an org owner or admin, and both
refuse an agent with a 403 before the role is even considered, so an agent
acting under an admin’s credential gets the honest answer rather than a role
complaint. There is no confirm tool over MCP. An agent proposes with
propose_nuance and that is its only write here.
Only a confirmed entry acts, and where one applies it is named: a readout that applied a nuance carries a disclosure line naming the rule and its tier. Every confirm and decline is recorded in your audit log, and so is each of the two refusals, under separate codes because the remediation differs.