Pressure-testing Ota on Hoppscotch: from runnable commands to execution governance

Hoppscotch is a strong pressure-test repo because it already has real commands, real contributors, and more than one legitimate way to operate the system. It is not one app with one loop. It is a pnpm workspace verification surface plus a documented self-host Docker stack with multiple runtime profiles.

That makes it useful for Ota because the hard part is not finding commands. The hard part is making sure local development, CI, and an agent choose the same path on purpose instead of mixing verification rules, runtime profiles, and host assumptions.

The goal here was not to add another command wrapper. The goal was to encode the repo's actual operating model so the path selection becomes explicit.

• scoped workflow intent: verification and runtime lanes are explicit instead of blended
• matrix signal quality: contract validity, dry-run planning, execution, and runtime proof are separate CI lanes
• agent boundary clarity: safe tasks, protected paths, and setup side-effects are explicit in the contract

Hoppscotch exposes exactly the kind of readiness drift that infra tooling has to handle well:

• native verification (lint, typecheck, test) through pnpm workspaces
• container-mode verification through declared execution context
• runtime workflows with different self-host profiles (selfhost, app, backend, admin)
• cross-OS contributors where Docker behavior and host capability differ

That matters because a repo like this can look well documented and still leave too much unsaid.

The root verification path is a Node workspace story: Corepack, pnpm, and root-level checks that contributors expect to run natively. The self-host story is different: .env setup, Docker Compose profiles, multiple published services, and a front door that should be treated as a runtime surface, not as a shell command that happened to keep running.

That split is where weak contracts get exposed. If everything is flattened into “install, test, run,” the contract stops being operational. It may validate. It may even dry-run. But it will still fail as a real decision surface.

Three things made this pressure test worth writing up.

First, verification and runtime are not the same lane. Hoppscotch has a clean root workspace verification path through pnpm, but the self-host path is Docker-first and profile-driven. Treating those as one workflow would hide the real difference between “this repo checks cleanly” and “this self-host stack becomes ready.”

Second, the runtime path is not one service. The documented Docker stack exposes an app front door, admin, backend, and bundle server. Ota needed to model those as named surfaces and then decide which surface anchors readiness for each workflow instead of pretending every port is equal.

Third, cross-OS confidence is easy to fake here. macOS and Windows can still prove planning and some native execution behavior, but Docker-backed runtime proof is realistically an Ubuntu lane. That is not a weakness in the repo. It is exactly the kind of host-capability truth the contract and matrix should make explicit.

The branch introduced a narrower, more honest readiness contract and matrix:

• ota.yaml with declared contexts for host-native, container task mode, and Docker host execution
• workflows for verification and self-host runtime paths
• explicit agent boundary (readiness_strict, safe tasks, writable/protected paths, bootstrap, notes)
• matrix lanes that separate contract validation, dry-run planning, execution, and runtime proof
• version discipline aligned to released Ota v1.6.18 (metadata.ota.minimum_version + pinned bootstrap commands)

The useful work here was not adding more names. It was drawing the boundaries in the same places the repo already draws them.

• verify is the native root-workspace proof path. It aggregates lint, typecheck, and test so the contract proves the full verification claim rather than one last task in isolation.
• verify:container exists because Hoppscotch can also execute those workspace checks inside a declared container context. That is a different execution statement from native verification, and it deserved a first-class workflow.
• selfhost stays tied to the documented all-in-one Docker profile, while app, backend, and admin exist as narrower runtime paths with their own readiness surfaces.
• setup:env is explicit and unsafe for agents because copying .env.example into .env is a real write, not harmless setup narration.
• desktop, relay, agent, and release flows stay out of scope on purpose. A pressure-test contract gets stronger by saying what it does not model.

Those distinctions are what make the contract useful to an operator or agent. Without them, the contract would still look neat while quietly asking the user to infer the real workflow shape from Compose profiles and CI files.

Before

• repo tasks were runnable, but readiness intent was spread across docs, scripts, and CI behavior
• workflow meaning depended on contributor interpretation
• dry-run and execution proof were not explicitly separated as CI signals

After

• one contract declares workflow intent, contexts, and readiness surfaces
• cross-OS matrix proves planning paths and execution paths distinctly
• non-internal task coverage is explicit in native and container lanes
• runtime proof is isolated to a dedicated self-host proof lane
• runtime proof is gated as an opt-in manual lane so required PR/push CI stays deterministic on hosted runners

The maturity move was making the matrix prove different claims separately, not as one blended signal.

Ubuntu full-proof lane:

• dry-run all non-internal tasks (native and container)
• execute non-runtime non-internal tasks (native and container)
• keep runtime validation in explicit proof workflow lanes

This prevents false confidence by clearly separating:

• contract validity
• path planning
• task execution
• runtime readiness proof

• PR: hoppscotch/hoppscotch#6382
• Upstream PR status: closed as not planned (maintainers noted existing CI and compose profiles cover their current needs)
• Contract: ota.yaml
• Matrix workflow: test-ota-contract-matrix.yml
• Latest green Apex matrix run: #26760486151
• Earlier alignment run: #26749379090

Hoppscotch reinforced the same pattern we keep seeing: runnable commands are not the same thing as execution governance.

This repo forced Ota to model two valid but different truths without collapsing them:

• root workspace verification is a native package-manager path
• self-host runtime is a Docker-profile and readiness-surface path

Trust comes from explicit scope and explicit proof lanes, not from one vague “works on my machine” signal.