[abrichr]

For Richard's review. Don't merge: openadapt-flow is frozen for the monorepo cutover. The branch is based on the freeze SHA eced892.

What's in it

Decision triage (from Chief Architect's feat/decision-triage). Commits 4ab7eb29, 1f4e236b and 6fc103fe are cherry-picked as bf02e90, 501a8c2 and 1243141, with authorship kept. The original branch wasn't changed.

Delegated approvers (openadapt_flow/approval_mode/approver.py, item_approval.py, gate.py, CLI)

• Each run has an approver policy (--approver-policy FILE, openadapt.approver-policy/v1). It's written once to item-approval/approver-policy.json and every reader applies it. With no policy, or an unreadable one, only a person may answer, so nothing changes without opt-in.
• An agent or system can answer by three routes, and only where the policy allows its kind for the step class:
  • local_cli: item-approval approve|decline --decided-by automation --delegate-kind agent|system --delegate-id ID
  • mcp: the same answer from an MCP tool (openadapt-agent feat: durable tiered runtime — checkpoint + pause/approve/resume from last verified state #80)
  • webhook: run --approver-webhook URL --approver-webhook-id ID, secret from OPENADAPT_APPROVER_WEBHOOK_SECRET. Flow sends PHI-free facts with HMAC-SHA256 in both directions, and the reply must echo the request digest. Any failure leaves the save to a person.
• Clinical writes:
  • Under the clinical-write and regulated policies, every save is clinical_write.
  • A clinical_write step takes a non-person approver only with a pinned opt-in digest.
• The report's ItemApprovalRef records decided_by: automation, the route and the approver. Person answers keep their old bytes.
• Only a person's decision becomes a triage label. Triage never approves.

Read-back field checks (ir.py, runtime/replayer.py)

• StepResult.effect_field_checks records field, typed value, value on file, matched, and tier, from field_equals and record-match effects. It's local report only and left out when empty.
• Triage --run-dir builds comparisons from it, so a confirmed save can now be clean. Desktop docs: rewrite workflow-program IR as an implemented spec + formalize semantics #203 uses the same data for its Check the record diff.

Tier rule (RFC-0002 names, decided rule)

• independent_readback is a read of the system of record that doesn't go through the UI: REST, SQL, FHIR, GraphQL or a file export (Flow tier 1).
• Tiers 2 to 4, including a UI read in a separate session, are screen_readback. They are never clean.
• Triage has a hard reason, readback_not_independent.

Triage items (a) to (d)

• (a) learned_fallback stays per_item. Whoever picks learned asked for a measured miss rate, and an uncalibrated group has none; rule_v0 is an explicit choice.
• (b) Field checks are persisted (above).
• (c) Recent declines flag only when there are more than 1, or more than 5% of recent items. So one decline among 20 or more items is tolerated. Setting both to 0 restores the old rule. Tested.
• (d) decision/eligibility.py adds TriageEligibilityProvider. It needs a pinned, eligible calibration artifact plus audit labels, and computes an exact Clopper-Pearson upper bound (bisection, no scipy) that must be under the target. It raises EligibilityUnavailable with a code when evidence is missing. openadapt-flow triage eligibility exits 0 eligible, 3 not yet, 2 no evidence.

Types mirror. Flow's core can't depend on openadapt-types (an optional extra, pinned below 0.22), so approver.py mirrors openadapt_types.approval (types #49). A conformance test checks the two match when both are installed. It passed against the types branch.

Docs

• New docs/APPROVAL_AND_VERIFICATION.md, a design note that includes the planned person-only Desktop path for check admit.
• APPROVAL_MODES.md: replaced the stale "Not built yet" list (Desktop feat: compiled-program visualizer (shared graph spec + CLI render) #184 and Cloud test: fix a Python 3.10 permit parse and a Chromium CDP readiness race #395 shipped).
• EXCEPTION_INBOX.md: now shows Desktop's real button labels from src/lib/attention.ts.
• DECISION_TRIAGE.md updated.

Not in this PR

• batch stays a post-save review in triage, not a runtime gate.
• Cloud refuses a run summary whose approval wasn't decided by a human (approvalModeContract.ts, "only a person answers an approval"). A delegated run would be refused there, which fails safe. Showing who approved needs a Cloud change.
• Eligibility isn't wired into the problems_only requirements yet.

Tests

• New tests/test_approval_delegated.py (21) covers:
  • the default policy refuses an agent, and clinical writes need the opt-in;
  • an agent can't pose as a person;
  • webhook signing, pending replies and bad replies;
  • delegate polling and failure;
  • person answers keep their bytes;
  • conformance with the types mirror, and the tier mapping.
• tests/test_decision_triage.py (67) adds the declines threshold, the tier rule, report field checks, Clopper-Pearson and eligibility.
• Approval-mode tests: 414 passed, 1 skipped, 3 xfailed. ruff check, ruff format and mypy (the whole package, plus strict on the touched safety modules) are clean.
• Full suite on a heavily loaded Mac: the only errors were in test_qualification_gate_campaign.py, at the 300 s per-test timeout. That file passes on its own (38 passed). A clean rerun is in progress.

[abrichr]

Carried over into the monorepo as OpenAdaptAI/OpenAdapt#1190 (merged as 921ba228e1a9ca1403634eacf9f5ae99d128fadf). openadapt-flow now lives in OpenAdapt/packages/flow.