Spec: Shared Effect API Contract Boundary

User Input

/goal Achieve the full M1 Monorepo Foundation Module milestone for the Devpunks Harness Intelligence project in /Users/stefan/Desktop/repos/wearedevpunks-cli.

Relevant IP-97 Linear scope:

• IP-97 defines the shared Effect API contract boundary so the CLI and backend share a typed Effect v4 API contract without importing each other's app code.
• IP-112 requires packages/contract to define baseline/channel resolution shapes and artifact URL/metadata response shapes consumed by both API and CLI.
• IP-113 requires the shared contract to model authenticated CLI requests and authorization failures without leaking Better Auth implementation details.
• IP-114 requires the CLI to use a generated Effect HttpApi typed client for control-plane baseline/auth/telemetry/reporting calls instead of raw untyped HTTP.

Context

Harness Intelligence now has separate apps/cli, apps/api, and packages/contract boundaries. The next foundation step is a shared control-plane contract that keeps API shape, schemas, security declarations, and typed client generation in one neutral package. The affected roles are CLI operators, backend implementers, and agents extending the monorepo: they need API changes to fail at typecheck time instead of drifting through raw HTTP strings.

Non-Goals

• Removing the existing GitHub stable-baseline fallback before a backend storage path exists.
• Implementing final artifact storage, release publishing, telemetry ingestion, or report persistence.
• Introducing Effect RPC before streaming or procedure semantics are proven necessary.
• Importing apps/api from apps/cli, apps/cli from apps/api, or either app from packages/contract.
• Leaking Better Auth internals into packages/contract.

Acceptance Criteria

• packages/contract exports a shared Effect v4 HttpApi definition for Harness control-plane calls.
• The contract includes typed baseline/channel resolution request and response shapes.
• The contract includes typed artifact URL/metadata response shapes.
• The contract includes typed authorization failure errors suitable for authenticated CLI calls.
• Authenticated request modeling is generic bearer-token based and does not expose Better Auth implementation details.
• apps/api imports @punks/contract and implements the shared contract with Effect HTTP router/layer primitives.
• The scaffolded Hono backend remains explicitly non-final and is not the source of the control-plane contract.
• apps/cli imports @punks/contract and exposes an Effect-native typed client path for control-plane calls.
• Raw untyped HTTP is not used for new baseline/auth/telemetry/reporting control-plane calls.
• Existing CLI baseline resolution keeps the current stable GitHub/bundled fallback behavior until backend storage is implemented.
• Root build, typecheck, test, and lint/format validation pass after the contract package is introduced.
• Docs/spec artifacts explain the package boundary: packages/contract owns shape, apps/api implements it, apps/cli consumes it.

Constraints

• Prefer Effect v4 HttpApi and typed client for v1.
• Keep packages/contract app-independent and side-effect free.
• Use Schema.TaggedError plus HTTP annotations for API-visible errors.
• Keep prompt/spec resolution logic in this repository; do not import consumer-repo business logic.
• The backend product direction is Effect HTTP router/layer architecture, using MultiplAI only as a structural reference.
• Operator workflow, setup, and AI scaffolding behavior changes must be reflected in docs/runbooks when they change.

Technical Notes

• The current CLI resolves baseline artifacts through GitHub release metadata and direct artifact downloads, then falls back to bundled content.
• Effect source examples show the intended pattern: HttpApi.make, HttpApiGroup.make, HttpApiEndpoint, HttpApiSecurity.bearer, HttpApiBuilder.group, and HttpApiClient.make/makeWith.
• The contract should start with baseline and artifact metadata endpoints because they are the only IP-112 acceptance surface. Telemetry/reporting can reuse the same client factory later without inventing raw HTTP.

Decision Log