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

Dated trail · spot stale claims

Dated trail of when this doc was last touched, what changed, and what to look at if it feels stale.

The machine-readable spec

Canonical fields, table names, endpoint signatures. What code should match, what tests should assert. workflow_type · hitl_approval_lifecycle · risk_level · N/A (substrate).

Inputs (required + optional)

D1 tables written

Endpoints called

Events fired

It broke at 2am — what now

Different from "how do I use this." This is the page Mike pulls up when something is wrong: logs to check, recovery steps, who to escalate to.

Logs to check

• workflow_run_log · top-level run audit
• workflow_step_log · per-step trace
• workflow_verify_results · post-window verify outcomes
• cron_locks · stuck cron lock detection
• events · workflow.completed / workflow.failed event trail
• reflexion_log · per-run narrative (if reflexion_enabled)
• npx wrangler tail · live Worker logs

Kill switch · emergency stop

If this workflow is misbehaving in a high-impact way (creating bad proposed_actions in volume, pushing wrong things to NS), flip a kill switch:

• kill:ns_writes · stops every NS push platform-wide
• kill:proposed_apply · stops HITL approvals from executing fan-out
• kill:high_risk_ops · stops risk_level >= 4 fan-out

See kill-switches-state-machine.html for the full state machine + recovery procedure.

Escalation

Primary: Mike Levine (single-admin) · mikelevine@globalfoodsolutions.co. For prolonged outage during business hours, notify warehouse lead + accounting lead so they can defer dependent work.

What's not done · what's uncertain

What's not done, what's uncertain, what we punted. Captured so it survives context switches and doesn't die in someone's head.

• OPEN
  Should risk_level < 3 still stage in proposed_actions?

  Today only risk >= 3 hits HITL. Risk 1-2 auto-execute. Doctrinal question: stage everything (with auto-approve for low risk) or skip the table?

• DEFER
  Multi-approver flow

  Today single-admin (Mike). If GFS scales to multiple admins, need approver roles + escalation if approver A unavailable.

• STUB
  SLA tracking on pending decisions

  Today no SLA. Could add 'expected_decision_within' per action_type and alert on breach.

• DECISION
  Auto-reject after N days?

  Pending rows accumulate. Auto-reject at 30d? Mike's call — might lose important draft work.