ADR-0011 vNext: session-contract surfaces beyond v1 + per-harness conformance suite

[aarontrowbridge]

Summary

Documentation-level amendment to the Harness Contract ADR (docs/adr/0011-harness-contract.md), drafting the vNext section named by spec-20260905-045114-session-device-lifecycle (§ Placement under harness-agnostic, the post-approval amendment). The ADR's v1 decision stands unchanged.

What the vNext section declares

• Three OPTIONAL richer session surfaces, each with its client-side fallback stated (the product is fully functional when a harness serves none of them):
  • Server-computed list currency — list-generation = (count, max time_updated, sum of time_updated) over the default-list projection + build id, computed per response, never hand-bumped. Fallback: the client derives the same token over the projection it fetches and checks it against boot-time fetch-before-render.
  • Server-side project resolution with first-class non-git homes — worktree-path-keyed project rows, boot backfill, git-init re-key. Fallback: client-side grouping over directory/projectID — data the global list already returns.
  • Boot parity records (three outcomes) — parity-ok | parity-drift | channel-unreachable; unreachable fails open but is never rendered as ok. Fallback: client-side parity check against the release channel using the server-reported version.
• The conformance-suite requirement (MUST, per harness): session-list query semantics (scoping keys, filter fields, defaults, v1 and v2) are declared surface; every harness — opencode canonical, Telaio.jl, future — is validated against the declared fixture set, and a semantics change without a companion fixture update fails that harness's conformance run. Generalizes the spec's fork-only H5 drift gate.
• Boundary note: richer surfaces are contract, not premium — they live in the public contract so every backend can serve them; premium (amicissimo) adds no contract fields. Upstream contribution to anomalyco/opencode is RECOMMENDED, not required.

Conventions

• Follows the repo's ADR amendment precedent (ADR-0001): a dated Status-line marker plus a clearly-marked trailing section; the section is titled vNext because the spec names it that way ("The Harness Contract (ADR-0011 vNext) carries OPTIONAL richer surfaces").
• Additive only — no v1 text was edited apart from the Status line.
• Spec referenced by vault-relative id (spec-20260905-045114-session-device-lifecycle), no absolute paths.
• No docs/ADR lint gate exists in CI (checked .github/workflows/ci.yml).

Tracking: the spec's reference is carried by amicode#817.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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.}