HITL approval flow

Mike is always the loop step

HITL means human-in-the-loop. Every AI-proposed action that would write to NetSuite, send a customer email, place an order hold, or change business state must first land in proposed_actions and wait for Mike's approval. This is the load-bearing invariant of the platform — encoded in ADR-031 and surfaced via /proposed-actions.html.

The reason is not paranoia about AI. The reason is that GFS runs on Mike's judgment. A 22% gross margin floor is a Mike rule. Which customers get softer collections treatment is a Mike rule. When to push back on a vendor versus eat a 5-cent cost increase is a Mike rule. The platform exists to amplify Mike's throughput — not to replace his judgment with a model's confidence interval.

Practically: every chat tool that mutates state writes a row to proposed_actions with a structured preview of what would change, a calculated risk_level, and a list of cascade targets. The work doesn't happen until Mike approves.

What requires approval

• Any push to NetSuite — price updates, customer record changes, vendor updates, item changes.
• Any outbound customer email — quotes, dunning letters, statements, notifications.
• Order holds and credit changes — anything that affects a customer's ability to transact.
• Vendor cost commits — they cascade too far to auto-apply.
• Spec deviation acceptances — these affect bid eligibility.

What does not require approval: read-only chat queries, internal D1 syncs from NS, sync reconciliation, log writes, event emission, draft generation (the draft itself is the proposed action — sending it is the gated step).

L1 through L5 + cumulative cap

How Mike approves things

The page polls GET /api/proposed-actions?status=pending every 10 seconds. Pending rows render as cards stacked by risk tier — L5 at top, L1 at bottom. Each card shows:

• Header — workflow type, customer/vendor/entity name, time created, risk badge.
• Diff preview — current value vs proposed value, side-by-side for prices; full email body for outbound.
• Cascade targets — list of tables and external systems that would receive the change.
• Edit link — for emails and quotes, Mike can edit the draft inline before approving.
• Buttons — Approve, Reject, Defer (writes a note), Edit (opens inline editor).

A floating "select all in tier" control lets Mike bulk-approve same-tier rows when appropriate. Keyboard shortcuts: A approve, R reject, D defer, E edit, ↑/↓ navigate, Cmd+Enter confirm typed-confirmation modal.

Single-decide vs bulk-decide

From propose to commit

1. 01

   Chat tool writes the proposed action

   Any chat tool that mutates state calls the shared writeProposedAction helper rather than the mutator directly. The helper inserts a row with action_type, payload_json (full preview), proposer (tool name), entity refs, and a calculated risk_level via the BEFORE INSERT trigger from 114_risk_level_trigger.sql.

   Writes proposed_actions (status='pending')

   Time ~100ms
2. 02

   UI polls + renders

   /proposed-actions.html polls every 10s and renders pending rows. New rows fade in with a tufts-bordered ring for the first 30 seconds so Mike spots fresh items.

   Reads GET /api/proposed-actions?status=pending
3. 03

   Mike reviews + decides

   Single-decide or bulk-decide. For L4/L5, a typed-confirmation modal prevents accidental approval. X-Edit-Token (from Mike's session) must accompany L5 approvals.

   UI /proposed-actions.html

   Time seconds to minutes
4. 04

   Atomic claim (R560)

   The approve handler does UPDATE proposed_actions SET status='approved', claimed_by=?, claimed_at=? WHERE id=? AND status='pending'. The AND status='pending' is the load-bearing clause — it prevents the double-approve race that hit us in R559 when Mike fat-fingered bulk-decide.

   Writes proposed_actions.status='approved'

   Invariant R560 atomic claim
5. 05

   Cascade executes

   The originating workflow's on_approval handler fires: NS push enqueued, D1 writes, KV invalidations, R2 artifact regen, event emission. The handler is idempotent on proposed_action_id — if it runs twice, the second run is a no-op.

   Writes per the workflow's cascade_tables_json
6. 06

   Audit + event

   Approval is logged to approval_audit with full payload. An event hitl.approved (or hitl.rejected, hitl.deferred) is emitted with proposed_action_id. Reflexion picks it up to evaluate the quality of the AI's proposal.

   Writes approval_audit, events

   Emits hitl.approved

What the substrate guarantees

• Every state-changing action has a traceable approval row with timestamp, approver, and full pre-state.
• No double-execution possible — the atomic claim guarantees exactly-once application.
• Rejections inform reflexion which steers future AI proposals away from rejected patterns.
• Compliance review can replay the entire decision history from approval_audit.

What can go wrong and how to recover

Adjacent substrate + workflows

Code paths + invariants