Human Control Plane

Purpose

Not every step should be fully autonomous. The human control plane is where Kobi operators and planners review, approve, reject, or override agent actions — with full audit and version linkage.

This document covers the Human Touch Dashboard only: business operations, approvals, and client-workflow surfaces. System health, logs, and engineering statistics live in a separate System Ops Dashboard behind IAP and/or VPN — not mixed into operator views.

Two surfaces (do not merge)

Principle: operators see what to decide (diff, SLA, summary). System users see why it failed (token rows, failure-code heatmaps, playbook versions, infra errors). Deep links from Human Touch tickets into System Ops are allowed for users with both roles — never embed BQ/GCS explorers in the operator inbox.

Design goals

1. No silent human work — If a human touches a platform manually, it must be logged or migrated into the system.
2. Single approval queue — All pending human touches in one inbox, filterable by tenant, platform, urgency.
3. Version binding — Every approval references a plan_version or change_set_id.
4. Rollback — Approved changes that caused issues can be reverted to prior version where platforms allow.
5. No engineering noise — Operators are not exposed to raw logs, model statistics, or infra panels.

Human touch categories

Human Touch Dashboard views

1. Approval inbox

• Pending items sorted by SLA; red flags (A8 / A9) pinned above standard approvals
• Fields: tenant, vertical, agent, requested action summary, diff preview, plan version
• Actions: Approve, Reject (with reason), Request changes
• A8 summary: loop type, attempt count, last QC failure reason (one line) — link to System Ops trace for engineers
• A9 summary: estimated vs actual USD, trip ratio — link to System Ops token breakdown
• A8 actions: Resolve (authorize new run_id), Manual fix, Admin override (A6), Cancel task — no "retry in place" on same run_id

2. Red flag queue

Operational view of open A8 / A9 tickets — not a statistics console.

• Open tickets across tenants; SLA and assignee
• Filters: loop type (QC / tool / timeout / global), cost trip, agent, platform, age
• Actions: resolve, escalate to engineering, cancel
• No BigQuery explorers, QC leaderboards, or Cost Guard ledgers here — those are System Ops

3. Tenant timeline

• Chronological audit: onboarding steps, plans, launches, optimizations, reports
• Filter by platform and actor (agent vs human)
• Business-readable events only; raw run_id traces open in System Ops

4. Plan diff viewer

Side-by-side comparison of plan versions:

• Channel budget split
• Target KPIs
• Campaign structure summary
• Tracking dependencies

5. Tracking health

• GA4 event volume, tag coverage, CAPI match rates (client-workflow signals)
• Blocks launch/optimization when red
• Detailed tag-debug and server-side logs → System Ops

6. Manual override form

When ops must act outside agents:

• Record platform, action, reason, ticket ID
• System schedules reconciliation job to sync state

Approval workflow

Roles (RBAC — Human Touch)

System Ops roles (system_developer, system_admin, sre) are defined in System Ops Dashboard — separate IAM group; may overlap with Admin for senior ops.

Versioning model

MediaPlan
  id: uuid
  tenant_id
  version: integer (monotonic)
  status: draft | pending_approval | approved | superseded
  approved_by, approved_at
  payload: channels, budgets, structures, rules

Campaign execution always stores plan_version on every platform mutation for traceability.

SLAs (planning defaults)

Related documents

• System Ops Dashboard — logs, statistics, system health (IAP / VPN)
• 05-human-in-the-loop.md — extended approval policy
• 07-security-access-governance.md — access tiers
• 04-lifecycle/plan-update.md