All runbooks
planuapiredacted view

UAPI Integrated Operating Plan v2

Clean v2 plan merging the UAPI redesign scaffold with ChatGPT Interpreter operating-image input and review cleanup notes.

Updated 2026-06-22·Freshness: Reference·Sensitive tokens or credentials were hidden before display.

UAPI Integrated Operating Plan v2

Clean v2 plan merging the UAPI redesign scaffold with ChatGPT Interpreter operating-image input and review cleanup notes.

Promotion Metadata

  • Source feedback id: 70
  • Source feedback ids: 70, 71, 72
  • Promotion request id: 7
  • Feedback category: beneficial
  • Feedback source: [REDACTED:high-entropy]
  • Feedback created at: 2026-06-22T15:58:19.427608+00:00
  • Target slug: [REDACTED:high-entropy]
  • Review state: review
  • Reviewer note: AI lane auto-promoted redacted feedback into internal catalog context.

Source Feedback Body

Feedback 70

  • Product: uapi
  • Category: beneficial
  • Related slug: [REDACTED:high-entropy]
  • Source: [REDACTED:high-entropy]
  • Created at: 2026-06-22T15:58:19.427608+00:00

UAPI Integrated Operating Plan v2

Status: review plan. This v2 merges the useful parts of the promoted UAPI redesign scaffold with the ChatGPT Interpreter First Wedge operating image and the later data-quality review. It supersedes the first promoted scaffold for planning discussion, while preserving that scaffold as lineage.

Executive Thesis

UAI should run as a set of clear, cooperating planes rather than one overloaded agent or one giant service. Explorer is the governed source of truth. UAPI is the unified control/API plane. Cadence is the operator-facing identity. Interpreter is the implementation of Cadence's PA/interpreter layer. Conductor is the separate execution/orchestration system. Cortex remains bounded memory and product intelligence. Beacon/Mesh and device/provider lanes support signals, coordination, capacity, and execution, but do not collapse into Cadence.

The surface behavior should feel like a capable voice-chat PA: concise, natural, context-aware, and calm. It should understand enough context to avoid making the operator repeat themselves, but it should not dump internal context, raw agent output, or speculative execution details. It asks only questions that block a safe handoff. It reports progress only from real events. It distinguishes fact, assumption, unknown, suggestion, and decision.

Ownership Boundaries

  • Explorer: source of truth for rules, docs, audit IDs, provenance, review state, public-safe catalog context, and approved documentation updates.
  • UAPI: unified API/control plane for identity, policy, routing, provider adapters, compute placement, run records, artifacts, and embedding jobs.
  • Cadence: locked operator-facing agent identity and personal-assistant persona.
  • Interpreter: Cadence implementation layer. It interprets operator intent, prepares job briefs, handles gates, summarizes event-backed progress, and presents results.
  • Conductor: separate factory/orchestrator. It selects workflows, roadmaps, agents, models, lanes, GPU/local resources, validation paths, and execution strategy.
  • Cortex: bounded memory and product intelligence. It does not own raw unrestricted memory or embedding execution.
  • Beacon/Mesh: signal, notification, coordination, and device/resource support lanes as approved by their own contracts.

Cadence/Interpreter delivers the what. Conductor determines and executes the how. UAPI provides the governed substrate that both can call. Explorer records what is known, approved, changed, or still draft.

Rules From The Feeder Input

Interpreter should not absorb Conductor's model routing, lane control, swarm management, roadmap execution, or worker allocation. UAPI should not become the UI or the source-of-truth documentation store. Cortex should not be used as a raw memory dump. Standard AI access and Cadence-admin access must remain separate, deny-by-default, auditable, and token-safe.

Feedback 71

  • Product: uapi
  • Category: beneficial
  • Related slug: [REDACTED:high-entropy]
  • Source: [REDACTED:high-entropy]
  • Created at: 2026-06-22T15:58:19.457854+00:00

UAPI Integrated Operating Plan v2 - Flow And Contracts

First Wedge Flow

  1. Operator gives a natural-language request to Cadence.
  2. Interpreter detects intent and retrieves only needed context through Explorer/UAPI-approved paths.
  3. If safe handoff is blocked, Interpreter asks one focused question. If not blocked, it proceeds.
  4. Interpreter builds a structured JobBrief with objective, constraints, assumptions, unknowns, context provenance, deliverables, acceptance criteria, presentation preference, and possible operator gates.
  5. Interpreter submits the brief through a Conductor gateway.
  6. Conductor emits ordered progress events. Interpreter deduplicates, rejects stale or malformed events, and reports concise event-backed status.
  7. If Conductor raises an OperatorGateRequest, Interpreter explains the decision and valid options, then returns the operator's approval, rejection, revision, or cancellation.
  8. Conductor returns a ResultPackage with outcome, artifacts, validation, deviations, unresolved items, and technical references.
  9. Interpreter presents a short result first and offers deeper evidence only when requested.
  10. Session, decisions, provenance, artifacts, and outcome are recorded through Explorer.

Mock Conductor is allowed only when the real contract or endpoint is unavailable or unsafe. The mock must implement the same gateway trait and contract as the real adapter.

Contract Names To Define Or Map

Before inventing schemas, map these to existing Explorer/UAPI/Conductor types where possible:

  • Identity
  • JobBrief
  • ProgressEvent
  • OperatorGateRequest
  • OperatorGateResponse
  • ResultPackage
  • ToolManifest
  • SessionRecord
  • DecisionRecord
  • RunRecord
  • Artifact
  • EmbeddingJob
  • PolicyBundle
  • PlacementDecision
  • ErrorEnvelope

Minimum common fields should include schema_version, job_id, session_id, correlation_id, trace_id, event_id, sequence, timestamp, objective, relevant_context, context_provenance, assumptions, unknowns, constraints, deliverables, acceptance_criteria, operator_gates, execution_state, blockers, artifact_updates, final_status, validation_results, deviations, and unresolved_items.

State Machines

Cadence brief state: Collecting -> NeedsInput -> Ready -> Submitted.

Conductor execution state: Queued -> Planning -> Running -> AwaitingOperator -> Validating -> Completed | Failed | Cancelled.

Interpreter may mirror explicit Conductor state. It must not invent execution state without a labeled rule and evidence. Events require monotonically increasing sequence numbers per job or another approved ordering mechanism. Duplicate, stale, out-of-order, impossible, or malformed events must be rejected or quarantined.

UAPI Responsibilities

UAPI owns the shared substrate: unified login/session model, service identity, policy checks, device/capacity inventory, provider adapters, placement decisions, run records, artifact references, audit hooks, and embedding job orchestration over sanitized context. It should route through adapters rather than pretending every host is local.

Feedback 72

  • Product: uapi
  • Category: beneficial
  • Related slug: [REDACTED:high-entropy]
  • Source: [REDACTED:high-entropy]
  • Created at: 2026-06-22T15:58:19.486843+00:00

UAPI Integrated Operating Plan v2 - MVP, Gates, And Cleanup

MVP Order

  1. Safe preflight: fetch Explorer rules, repo instructions, branch/toolchain state, dirty files, protected paths, secrets policy, and current contracts.
  2. Cadence lineage: research Cadence v1-v6, Director primitives, current Cadence v6 behavior, and migration candidates before schema invention.
  3. Boundary ADRs: lock Explorer, UAPI, Cadence, Interpreter, Conductor, Cortex, Beacon/Mesh responsibilities.
  4. Explorer access profiles: standard AI versus Cadence-admin, with wrong-role and missing/expired credential tests.
  5. Core contracts and state machines: JobBrief, events, gates, result package, error envelope, run records.
  6. Interpreter intake: natural-language request -> blocking-question detection -> valid JobBrief.
  7. Conductor gateway: mock first if needed, real adapter only when contract and endpoint are safe.
  8. Progress, gate, result handling: concise status, operator decision round-trip, validated result presentation.
  9. Explorer recording: session, decisions, provenance, artifacts, docs update, and evidence.
  10. One deterministic demo and review loop before broader GPU/provider/embedding expansion.

Gates

Gate 0: inventory, contracts, and role boundaries proven. Shadow mode: run mock/real or old/new paths in parallel without migration claims. Canary: one non-destructive workload completes with ordered events, gate handling, validation, and artifact recording. Rollback: old path remains available until comparison and recovery are proven. Broader rollout only after tests, security review, operator UX review, and Explorer evidence exist.

Embedding Ownership

Cortex remains memory/product intelligence. UAPI owns embedding jobs and pipelines over sanitized, provenance-bearing, AI-visible context packets. Explorer remains source of truth for public-safe context and audit. No raw/private data enters embedding lanes without redaction, provenance, and approval.

Non-Goals

No autonomous task initiation, proactive scheduling, hidden background work, self-modifying tools, unrestricted model/swarm control, dynamic code activation, raw Cortex memory access, public-route changes, separate product logins, or Cadence-owned scheduling/resource allocation in the first wedge.

Cleanup From Prior Scaffold

This v2 intentionally removes the first promoted scaffold's artifact problems: stacked frontmatter, stray numeric line, duplicated source_feedback metadata, redacted slug inside plan prose, and self-instructions telling future agents to promote it again. The prior plan remains useful lineage; this v2 should be the cleaner review target.

Definition Of Done For The Wedge

A first wedge is done only when the operator request to Cadence/Interpreter reaches Conductor through a validated brief, progress and gates are event-backed, a result package is presented concisely, Explorer receives provenance and outcome records, access-role separation is tested, no secrets leak, and every completion claim has evidence.