# HITL-001 evidence pack — human-usable V1 autonomy operator console

## Work-package charter

- **Task ID:** `HITL-001`
- **Owner:** Oshun V1 autonomy and operator-surface maintainers; implementation
  owner: Codex
- **Accountable product:** V1 Oshun autonomous-content platform
- **Priority:** P0
- **Target milestone:** 2026-07-15 SOTA gap-closure program
- **Risk tier:** Critical human-authority, stale-approval, destructive-release,
  concurrent-edit, and inaccessible-control risk
- **Dependencies:** The bound V1 creative-autonomy plane and its authenticated
  BFF routes; RUN-004 creative-cycle adapter; RUN-005 common lifecycle
  vocabulary
- **Affected runtime and UI:** `/v1/agentic/autonomy/*`, editorial lifecycle and
  durable plane snapshot, `/operator/autonomy`, shared web API errors, operator
  surface index, and focused Playwright coverage
- **Rollout strategy:** Ship the new operator route beside the existing
  read-only operator index. Keep the autonomy plane fail-closed when its LLM is
  unconfigured while leaving authenticated observation and steering available.
- **Rollback strategy:** Revert the web route, BFF response/action extensions,
  post-publication lifecycle methods, run adapter mappings, and tests together.
  Existing durable snapshots remain readable because publisher records are an
  optional backward-compatible field.
- **Evidence-pack location:** This file

## Shipped operator surface

`/operator/autonomy` is a client-operated, authenticated route inside the
existing Oshun operator shell. Its visual thesis is a calm editorial control
ledger: a paper/ink/terracotta queue-to-inspector workspace that keeps
authority, evidence, and outcome state above decoration. The console waits for
the shell's access token before its first request, sends the bearer on every BFF
call, and does not contain fixture data or a fixture/live mode switch.

The overview loads the plane status, cycle history, review queue, standing
direction, and learner suggestions in parallel. The inspector exposes seven
explicit views—run, artifact, provenance, source, budget, gate, and
interventions—while the queue is filterable by the five operational outcomes:
held, blocked, failed, review-window, and released. The status band names the
configured cycle budget, spent units, active work, queued work, steering
version, and whether the director is configured.

## Human authority and real endpoint binding

| Operator control   | BFF operation                                     | Concurrency/authority behavior                                                                 |
| ------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Approve            | `POST review-queue/:itemId/action` with `approve` | Sends expected history length; stale writes return 409 and refresh the item.                   |
| Reject             | Same endpoint with `reject`                       | Confirmation captures a decision note.                                                         |
| Veto               | Same endpoint with `veto`                         | Destructive copy names the stopped release window.                                             |
| Tweak              | Same endpoint with `request-tweak`                | Applies direction to the canonical review item.                                                |
| Node tweak         | Same action plus `nodeAddress`                    | Preserves a plan-node address in the intervention history.                                     |
| Standing direction | `PUT steering`                                    | Sends `expectedVersion`; a concurrent write returns the authoritative direction.               |
| Feedback           | `POST feedback`                                   | Records one 1–5 rating per item/rater and refreshes learner state.                             |
| Withdraw           | Review action plus publisher `withdraw`           | Requires a reason and executes the real `published -> takedown` editorial transition first.    |
| Roll back          | Review action plus publisher `rollback`           | Requires a reason and executes the real `published -> deprecated` reversible transition first. |
| Run cycle          | `POST cycles/run`                                 | A separate confirmation warns that provider usage may be billable.                             |

Withdrawal and rollback are separate terminal review states and map through the
RUN-004 creative adapter to cancelled/rollback interventions, withdrawn or
invalidated artifacts, and corresponding release transitions. The editorial
publisher's records and complete gate/transition history now round-trip in the
durable plane snapshot, so a restart does not strand a published item that an
operator must later reverse.

## Freshness, failures, and recovery

Every queue summary and detail carries an authority snapshot. Evidence age is
compared with its recorded half-life; stale evidence is announced explicitly,
and an approval based on that evidence receives a separate stale-approval
warning. A 409 `stale_review_item` or `stale_steering_version` is retained by
the shared API error client, shown as a concurrent-edit message, and followed by
a refresh rather than a blind retry.

The console distinguishes initial loading, live, disconnected, and service error
states. Browser `offline`/`online` events disable mutations and trigger a
reconnect refresh. A manual refresh, retry connection, and full page reload all
reconstruct state from the BFF. Authorization failure names the missing
agentic-operations scope; anonymous navigation remains proxy-gated away from the
operator route.

## Accessibility and destructive-action law

- Queue rows, tabs, dialogs, filters, and actions use native controls or named
  button/group semantics with visible `:focus-visible` treatment.
- Queue items activate by keyboard, tab state is announced, and action dialogs
  move focus into the first field, trap Tab/Shift+Tab, close on Escape, and
  restore a predictable inspector state.
- Withdraw, rollback, veto, and cycle execution use explicit confirmations.
  Withdrawal copy says the live artifact becomes unavailable; rollback copy says
  the published version is deprecated and retained in history; cycle copy warns
  about billable provider work.
- The 390-pixel mobile journey has no horizontal document overflow, while the
  desktop layout keeps the queue and inspector in one restrained split view.
- The shared Playwright fixture runs automated serious/critical Axe checks on
  the focused browser journeys, and the component honors reduced motion.

## Browser-to-real-BFF proof

`operator-autonomy-live-bff.spec.ts` starts from the shipped browser route with
an authenticated `admin:agentic-operations` identity and no interception of an
autonomy endpoint. Against a fresh real BFF process it observes successful
responses from status, cycles, review queue, steering, and suggestions. It then
opens the standing-direction drawer, submits a `PUT /steering` containing the
loaded version, observes HTTP 200 and version `N + 1`, and reopens the control
to verify the canonical value returned by the BFF.

The focused run passed **1/1** in Chromium against Next on `127.0.0.1:3011` and
a fresh BFF on `127.0.0.1:4110`. The BFF log recorded the five authenticated
reads, the version-checked mutation, and the subsequent refresh reads. This is
browser-to-runtime proof, not only an injected HTTP-handler test or a mocked UI
contract. The deeper action matrix remains deterministic: BFF integration tests
exercise the real queue/publisher/domain stores, while browser contract tests
exercise every corresponding human control and response branch.

## Automated scenario matrix

| Scenario                  | Enforced result                                                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| All observation views     | Queue, run, artifact, provenance, source, budget, gate, and intervention data render from response fields.                                  |
| All human actions         | Approve, reject, veto, broad tweak, node tweak, direction, feedback, withdraw, rollback, and cycle confirmation issue the intended request. |
| Outcome truth             | Held, blocked, failed, review-window, and released are separately visible and filterable.                                                   |
| Stale authority           | Evidence and approval warnings render; review and direction conflicts refresh instead of overwriting.                                       |
| Authentication            | Every autonomy request carries bearer auth; missing operator scope and anonymous navigation fail visibly/closed.                            |
| Error recovery            | Reload, offline/online reconnect, transient service error, refresh, and retry recover the console.                                          |
| Accessibility             | Keyboard operation, focus trap, Escape dismissal, native naming, mobile overflow, reduced motion, and Axe serious/critical checks pass.     |
| Post-publication recovery | Editorial transition history survives a plane snapshot restore and still accepts a real takedown.                                           |
| Live browser path         | A shipped Next route reads and version-mutates a fresh real BFF autonomy plane.                                                             |

## Artifact identity

| Artifact                                                                    | SHA-256                                                            |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `apps/oshun/bff/src/agentic/autonomy-route.ts`                              | `aceeecf3f155ad6009caea116219531a73c1029d79666c4f3e9b1a22493a1c01` |
| `apps/oshun/bff/src/agentic/autonomy-bindings/editorial-publisher.ts`       | `c3c5b0649e9f4e502d6b0d220f09c975c7934f5c5870420606c157c6bc330ddc` |
| `apps/oshun/bff/src/agentic/autonomy-bindings/plane-persistence.ts`         | `f41c6f33c9cd23b7c07cde5dad1ade7a9bde6f496df28277187e28f3b9fb1919` |
| `apps/oshun/web/src/components/operator/AutonomyOperatorConsole.tsx`        | `eb1eec271031754f936f42919fcc11707289672c201a9152bff1549f383010da` |
| `apps/oshun/web/src/components/operator/AutonomyOperatorConsole.module.css` | `fdcf186d743d8f417bb98fb8bf764ecec4613f3016d911a3df0007cf9798857d` |
| `apps/oshun/web/e2e/operator-autonomy-console.spec.ts`                      | `90738aa15a5e26d293c42f80bbb9c71a3b4cb2a32a38208588bd1586204dceea` |
| `apps/oshun/web/e2e/operator-autonomy-live-bff.spec.ts`                     | `85595215fd1f7f6838720740d93fd0c2a2d7ac7f598cfea276f9ed36f7c2e203` |
| `libs/oshun/creative-autonomy/src/review/review-queue.ts`                   | `e49c29e34d874af9285bc55e8c56be396cdbbe124b21add86cb9d935dbeec1e5` |
| `libs/oshun/creative-autonomy/src/common-run-adapter.ts`                    | `1036e6517221fc84c4343212a5d8995e296cca0722252a2f4f63f01be3b3c696` |
| `libs/contracts/src/run-protocol/run-model.ts`                              | `b22b8a192934d6ac3459f4aa3bdfaf5e996bc3df1d24894fcbfd60794078ef50` |

## Automated and adversarial verification

- The focused creative-autonomy suite and full package test target pass,
  including withdrawal/rollback transitions and post-publication common-run
  mappings. The contracts run-model test passes **19/19**.
- BFF route, binding, and plane integration tests pass **38/38**. They cover
  auth/scope refusal, category/budget status, freshness, queue and steering
  optimistic concurrency, node-addressed tweaks, live editorial withdrawal and
  rollback, and snapshot/restored reversal.
- The shared API-client unit slice passes **4/4**, including preservation of BFF
  error codes and conflict details.
- `operator-autonomy-console.spec.ts` passes **5/5** with retries disabled;
  `operator-surfaces.spec.ts` passes **7/7**; and the real-BFF browser journey
  passes **1/1**. Together these are **13/13** clean focused Playwright
  journeys, with the shared serious/critical accessibility scan applied to the
  mocked deep console and operator-surface paths.
- `@oshun/creative-autonomy:typecheck`, `@oshun/bff:typecheck`, and
  `@oshun/web:typecheck` pass; both app ratchets report zero baseline errors.
  The contracts production build and direct BFF production esbuild pass.
- Direct ESLint across every changed TypeScript/TSX file reports zero errors;
  the creative-autonomy project lint reports zero errors and only its 87
  pre-existing warnings. `git diff --check` passes.
- The refreshed canonical AUD-003 record passes all required boundaries at the
  evidence source commit: creative autonomy **255/255**, agentic studio
  **289/289**, studio authoring **138/138**, focused BFF autonomy/run lifecycle
  **43/43**, V8 **355/355**, and V9 **176/176**. Its deliberately
  verdict-recording V8 documentation-drift check remains red rather than being
  misreported as a test-execution failure; all record hashes, bounded logs,
  commands, source/lockfile identity, and generated audit sections verify.

## Resource-safe verification

The required resource probe reported 15 GiB RAM, 31 GiB swap, about 10 GiB
available RAM, and 38 GiB free disk. Checks ran sequentially with one focused
worker where applicable. A contracts Nx test wrapper unexpectedly expanded to
the repository-wide Vitest configuration and a BFF Nx build wrapper expanded to
269 dependency tasks; each was stopped under the hard memory gate and replaced
by its exact targeted Vitest or direct esbuild command. No test assertion had
failed when either wrapper was stopped.

A Next production build was not run: the host is below the 32 GiB threshold and
the repository instructions prohibit Next production builds by default without
explicit approval on this host class. The final web typecheck passed, both Next
dev routes compiled, the deep Playwright tests passed, and the retained live-BFF
journey exercised a fresh Next/BFF pair. No full-workspace sweep was attempted.

## Scope and negative proof

- This package proves the in-repository shipped browser route and an isolated
  local browser-to-real-BFF mutation. It is not evidence of an externally hosted
  production deployment, production traffic, a release canary, or a current
  production placement receipt.
- The isolated BFF intentionally ran without `OPENROUTER_API_KEY`; its director
  was fail-closed. No paid provider call, autonomous production cycle, customer
  publication, or real customer feedback occurred.
- No product database migration was added. In a database-backed deployment the
  plane uses its existing durable snapshot store; the new editorial-record field
  is backward compatible and is covered by restore testing.
- HITL-002 through HITL-005 still own the complete intervention vocabulary,
  canonical transactional co-authoring, notifications/escalations, and global
  shortcuts/presets. This closure does not claim those packages.
- No mobile-native flow, media/model artifact, or Unreal asset changed. Native
  mobile automation, media-provider probes, and Unreal execution are therefore
  inapplicable to HITL-001.

## Publication identity

- **Implementation and first remote-integrated tested source commit:**
  `06fe5f10396c0f52e22ccb92bfbb8f3369cb8401`
- **Retained browser-to-real-BFF proof commit:**
  `7244cd392183bc26c1fa4f18b65b61ede1ada8a4`
- **Publication metadata commit:** `6dd993da7e47c8b52085bedc55be10d8fad174dd`
- **Canonical verification refresh:** `6e9fe8f8238db551b04bdae39277beef4b615506`
