Seam: contract hygiene — dangling ADR 0022, version handshake, label-default SSOT

[kyle-sexton]

Parent

Refs #2933. Source: topic pocock-shipping-breakdown (PR backfilled when opened). Evidence: topic memory slice seam-scrutiny-findings.md (F3.5, F3.6, F3.7) plus one session finding.

What to build

• F3.5: CONTRACT.md cites "ADR 0022" but docs/adr/ holds only 0001–0013 — the seam's direction-locking rationale is uncitable in-tree. Locate or write the ADR (or correct the citation).
• F3.6: no contract-version handshake at the adapter seam — the dispatcher reads only .verbs from a manifest and never compares the adapter's schema_version to the core's, so a consumer-local/shadowing/generated adapter skews silently. Add a directional tolerant-reader handshake (standards-contract precedent). Prerequisite for the adapter-onboarding skill.
• F3.7: role-label defaults are triple-defined (binding.sh, frontier.sh parameter default, dispatcher inline fallback) — consolidate to one definition source. Also record (or leave deferred with a recorded posture) the [Maintenance] title prefix + recurring-schedule path fixed strings.
• Session finding (2026-08-17): the seam has no degradation path when gh is absent — cloud sessions (no gh CLI, MCP-only GitHub access) cannot run the github adapter at all; this topic's own board had to be published via MCP with body-text blocker edges. Document the limitation honestly in CONTRACT.md and evaluate an API/MCP fallback or a documented backfill ritual for native edges.

Acceptance criteria

• ADR citation resolves in-tree
• Version handshake implemented with conformance coverage; skew behavior documented both directions
• Label defaults single-sourced; fixed-string postures recorded
• gh-absent degradation documented (and fallback decided or explicitly deferred)

Blocked by

None — can start immediately.

[kyle-sexton]

Close-out (session 2026-08-17, per #2933's execution contract — apply → verify → close via PR #2970, which closes this item on merge). Acceptance criteria → evidence:

• ADR citation resolves in-tree — ✅ ADR 0014 (docs/adr/0014-resolve-seam-engine-plugin-canonical-and-adapters-consumer-first.md) records the direction-locking rationale plus the no-standing-sandbox conformance note; the dangling "ADR 0022" citations in CONTRACT.md and conformance/bindings/github.sh now point at it.
• Version handshake implemented with conformance coverage; skew behavior documented both directions — ✅ wit_check_contract_version (lib/json.sh) runs before every dispatch: major skew refuses (exit 3, both versions + direction-appropriate fix named), newer-minor proceeds with a stderr notice, older-minor proceeds silently, unversioned manifests refuse. Documented in CONTRACT.md "Contract-version handshake"; covered by 9 dispatcher unit-test assertions and synthetic-skew conformance cases (local-markdown 76/0, jira 29/0, both also green under a gh/curl-blocking shim).
• Label defaults single-sourced; fixed-string postures recorded — ✅ shipped role-label defaults now live once in lib/labels.sh (binding resolution, frontier filter default, and dispatcher all read the constants); [Maintenance] prefix + recurring-schedule path recorded as deliberate deferrals in label-taxonomy.md "Recorded postures: fixed strings without a remap seam".
• gh-absent degradation documented (and fallback decided or explicitly deferred) — ✅ CONTRACT.md "Degradation without gh (cloud / MCP-only sessions)": REST fallback explicitly deferred (recorded rationale: duplicated auth/pagination/endpoint surface, forked identity routing), MCP-as-adapter rejected (shell seam cannot call model-plane tools), and the backfill ritual is the documented supported path — which also formalizes the native-edge backfill this board itself still owes (Lane E: re-decompose (rerouting) flow in decompose #2949←Lane A: spec-on-tracker lifecycle — publish, pass-by-reference, close-at-ship #2934, Adapter-onboarding skill — generator for the provider tail #2950←Seam: contract hygiene — dangling ADR 0022, version handshake, label-default SSOT #2942, Jira write support — guarded, opt-in #2951←Investigation: multi-provider topology — source-of-record + coordination split #2945, Gitea/Forgejo adapter — generator dogfood candidate #2952←Adapter-onboarding skill — generator for the provider tail #2950).

---

Generated by Claude Code