docs: clarify governed decisions

docs/concepts/halt-learn-loop.md

@@ -9,6 +9,22 @@ when that person teaches the fix**, which is the halt-learn loop proper.
 Both halves refuse rather than guess. Neither hands control to a free-form
 agent, and neither puts a model call on the runtime path.
 
+## Terms used here
+
+- **BYOC** means bring your own cloud: a customer-owned cloud runner and
+  storage boundary. It is one form of customer-controlled execution.
+- An **effect verifier** independently reads the system of record to confirm a
+  declared write. It does not treat a screen message as proof.
+- **Qualification** is the versioned evidence that one exact workflow behaves
+  correctly in its named application, environment, and execution surface.
+- An **identity gate** checks the intended record before a consequential action
+  and halts if it cannot verify that record.
+- **Reconciliation** rechecks a possible or conflicting effect without
+  re-dispatching the action.
+
+See the [full glossary](../reference/glossary.md) for the shared terms and
+their contract boundaries.
+
 ## Where a halt goes: the attended decision
 
 When a run cannot confirm something, it stops and projects the paused step into
@@ -20,6 +36,19 @@ ambiguity, a human-only step, saved-result verification, uncertain delivery, or
 a required halt. The runner offers only the actions that are safe for that
 request.
 
+### Operational decisions are bounded; business judgment stays human
+
+An attended decision manages an **operational halt**. It can ask an authorized
+operator to prepare the live state, stop, skip an explicitly permitted step,
+escalate, teach a correction, or reconcile a possible effect. The signed task
+binds the exact run, pause, permitted actions, and revalidation requirements.
+
+It does not ask OpenAdapt to make arbitrary business judgment. A workflow that
+needs a business choice must either express that choice as a reviewed typed
+decision contract with permitted actions and a verifiable outcome, or stop for
+a human to complete the action. After either path, the runner rechecks the live
+identity, state, and configured effect before it reports `VERIFIED` or resumes.
+
 The question is closed by construction. `openadapt-flow` projects the pause into
 a signed task carrying typed categories, bounded counts, and digests; the client
 owns every sentence a person reads. The runner never sends prose and the phone

docs/guides/qualify-a-workflow.md

@@ -60,24 +60,28 @@ conflicting records remain refusal conditions.
 
 ## Safe entity language for attended decisions
 
-The released signed decision schema and Cloud receiver can preserve an approved
-entity class and neutral fallback. The Flow and Desktop controls that set the
-class are in the coordinated V2 release work.
+The released `HumanDecisionTaskV2` schema and Cloud receiver define the target
+contract for an approved entity class and neutral fallback. Flow 1.30.0 emits
+only `HumanDecisionTaskV1`: it does not yet store or emit the V2
+qualification-bound entity class. Until the coordinated Flow and Desktop
+release, use the neutral `record` or `item` wording and do not edit a signed
+task or sealed artifact by hand.
 
 The class is optional presentation metadata. It does not require a separate
 author role, and its absence does not block qualification, certification, or
 execution.
 
-After that release, the person or tool that prepares the qualification can
-select a static class for a step that can halt for an operator. For example,
-use `patient record`, `insurance claim`, or `loan application`. This class
-describes the kind of item. It never contains the live identity of the item.
-
-The class and a neutral `record` or `item` fallback become part of the exact
-qualification contract. A signed decision task carries the approved class to a
-remote operator surface. The receiver renders only reviewed safe classes and
-uses the fallback when no class was set or when it cannot validate the class.
-A class change creates a new qualification revision and requires
+With the coordinated release, the person or tool that prepares the
+qualification can select a static class for a step that can halt for an
+operator. For example, use `patient record`, `insurance claim`, or `loan
+application`. This class describes the kind of item. It never contains the
+live identity of the item.
+
+The target contract binds the class and a neutral `record` or `item` fallback
+to the exact qualification. A signed V2 decision task carries the approved
+class to a remote operator surface. The receiver renders only reviewed safe
+classes and uses the fallback when no class was set or when it cannot validate
+the class. A class change creates a new qualification revision and requires
 recertification.
 
 OpenAdapt never infers this language from a screen, OCR, parameters, an

docs/reference/glossary.md

@@ -50,6 +50,14 @@ document hash, not the pixels — and a non-confirmed verdict halts the run.
 Reports record them as one-way SHA-256 digests. See
 [Effect verification](../concepts/effect-verification.md).
 
+## Effect verifier
+
+An **effect verifier** is the configured independent read that evaluates an
+[effect contract](#effect-contract). It reads the system of record, such as an
+API, database, audit feed, or document store. A verifier does not infer a
+write from screen pixels. Its confirmed, refuted, or indeterminate result
+decides whether the run can continue.
+
 ## Halt
 
 The runtime's fail-closed refusal to act: when identity, a postcondition, an
@@ -68,6 +76,13 @@ wrong-record guard. A conflict or an unreadable identity band halts the run
 rather than clicking into the wrong record. See
 [The identity gate](../concepts/identity-gate.md).
 
+## Reconciliation
+
+**Reconciliation** is a no-re-dispatch check after delivery is uncertain or an
+effect conflicts with the requested result. The runner reads the required
+postcondition and independent effect again. It reports a reconciled result only
+when that read proves the effect; otherwise the run stays halted for review.
+
 ## Policy
 
 A reviewable YAML document (or built-in, such as `clinical-write`) stating