docs(adr): Harness Contract v1 — the fixture-pinned opencode API subset (A2, #621)

[aarontrowbridge]

Closes #621.

A2 of the harness-agnostic campaign: the decision record that defines what "a harness" means to Amicode, so telaio (subscription) and third-party harnesses implement a written, fixture-tested contract instead of an interface that drifts silently.

The three decisions

1. Compat-first — Harness Contract v1 IS the fixture-pinned subset of the canonical opencode server API the product consumes. No neutral protocol for v1 (rationale in the ADR: the app bundle / SDK / iframe investment rides unchanged; the golden-fixture technique is already proven by the PRD: Ship canonical opencode with Amicode — retire the fork-built binary from user machines #451 route port).
2. Product-owned tools — the amicode_* surface belongs to the studio; its portable carrier is an MCP server (A3, seeded); harnesses may implement natively where stronger.
3. The adapter seam — one extension-side seam owns harness selection; harness identity lives in settings and product copy, never in wire protocol strings (protocol-blocklist.json constraint).

The deliverable

The contract surface as a consumer × surface × evidence matrix (lifecycle+auth, ?auth_token= web-app bootstrap, /event SSE envelopes, the SDK-consumed session/turn API, the injection channels, the tool surface), with explicit non-goals (full opencode API, the 35-file server-coupled worklist, the TUI) and the enforcement story (golden fixtures + drift gates; fixture refresh = contract version bump).

Docs-only — no code changes. Drafted by the director in a worktree off main (the shared checkout is mid-bug-work); CI should ride the existing build gates unchanged.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ecb40ed4-bc2d-41ed-a094-c1b26b25ac31

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[aarontrowbridge]

CI note — the app-bundle-gate failure is inherited from main, not from this diff (docs-only; every other check is green).

Diagnosis: #620 hand-edited two overlay files (titlebar-channel.ts, titlebar-channel.test.ts — the dev→DEV / beta→BETA sync) without touching manifest.json, so the committed overlay no longer matches the .16-pin extraction. Full analysis and the two repair paths are in the linked repair issue. This PR stays ready-for-review and will merge once main is green again (rebase if needed).