work-items: define how consumer-local / shadowed adapters resolve the shared seam lib/

[kyle-sexton]

Follow-up from #224 (bundle work-item-tracker seam, shape A). This is the DESIGN half of the P1 surfaced in #224 re-review; the silent-corruption half was already fixed in-PR (commit 9b8ed32 — adapters now hard-fail with exit 3 on a missing required seam lib instead of emitting an empty-id record). This issue tracks the remaining resolver-contract design decision.

Problem

The two-rule resolver #224 introduces supports a consumer shadowing a bundled adapter with a local copy at ${CLAUDE_PROJECT_DIR}/tools/work-item-tracker/adapters/<provider>/ (CONTRACT.md "Adapter resolution"). But each adapter's common.sh sources the shared seam libs relative to the adapter's own directory:

source "$WIT_<X>_ADAPTER_DIR/../../lib/id.sh"   # id / json / lease

When the adapter is the bundled copy, ../../lib is the seam's own lib/ (present). When the adapter is a consumer-local shadow, ../../lib points at a consumer path that has no lib/ — so a shadowed adapter cannot resolve the shared seam libs. This applies to the github and local-markdown adapters identically.

As of 9b8ed32 this now hard-fails cleanly (exit 3 + diagnostic) rather than corrupting the store, but a shadowed adapter still cannot actually run.

Decision needed

How should a shadowed consumer-local adapter resolve the shared seam lib/? Candidates:

1. Seam-root resolution — the dispatcher exports its own seam root (it already knows $SCRIPT_DIR), and adapters source lib/ from that root rather than relative to their own dir. Lets a shadow reuse the bundled lib/ without copying it.
2. Self-contained adapters — an adapter carries (or vendors) the lib helpers it needs, so a shadow is fully portable.
3. Documented copy requirement — the contract states that shadowing an adapter also requires providing the seam lib/, and the hard-fail diagnostic points at that requirement.

Whichever is chosen, update CONTRACT.md "Adapter resolution", apply it to both bundled adapters, and add conformance/dispatcher coverage for the consumer-shadow path (the existing throwaway-fixture demo covers shadowing but not the lib-resolution edge).

[kyle-sexton]

Decision brief — how a shadowed adapter resolves the shared seam lib/

Decision-briefing lane: this is analysis for a human operator. It decides nothing, changes no labels, and closes nothing.

Problem (2 sentences)

The two-rule resolver from #224 lets a consumer shadow a bundled adapter with a local copy at ${CLAUDE_PROJECT_DIR}/tools/work-item-tracker/adapters/<provider>/, but each adapter's common.sh sources the shared seam libs relative to its own directory ($..._ADAPTER_DIR/../../lib/…), so a relocated copy resolves ../../lib into a consumer path that has no lib/. As of 9b8ed32 this hard-fails cleanly (exit 3 + diagnostic) instead of corrupting the store — so the remaining decision is purely how a shadowed adapter should correctly find the bundled lib/.

What's verified today (cited, current main)

The adapter-relative sourcing is identical in both bundled adapters:

• adapters/github/common.sh — WIT_GH_ADAPTER_DIR set L11; sources "$WIT_GH_ADAPTER_DIR/../../lib/{id,json,lease}.sh" at L29/32/35.
• adapters/local-markdown/common.sh — WIT_LOCAL_ADAPTER_DIR set L17; sources "$WIT_LOCAL_ADAPTER_DIR/../../lib/{id,json,lease}.sh" at L35/38/41.

Why it breaks under shadowing: ../../lib is only the seam's real lib/ when the adapter sits inside the bundled tree. A consumer-local shadow lives at ${CLAUDE_PROJECT_DIR}/tools/work-item-tracker/adapters/<provider>/, whose ../../lib is a consumer path with no seam libs. The hard-fail guard (wit_gh_require_seam_lib / wit_local_require_seam_lib, immediately above each source) turns this into exit 3, so the corruption is gone but a shadowed adapter still cannot run.

Key mechanism the fix hinges on (grep-confirmed in work-item-tracker.sh): the dispatcher computes SCRIPT_DIR (its own seam root, L10), resolves the adapter dir with plugin-bundled fallback at $SCRIPT_DIR/adapters/<provider> (wit_resolve_adapter_dir, ~L44), and invokes each verb as a child process via bash "$adapter_dir/$verb.sh" (~L203). It sources its own lib/ from $SCRIPT_DIR/lib (L12/14/16). It does not export SCRIPT_DIR today, so the child adapter cannot see the running engine's seam root.

CONTRACT.md "Adapter resolution" (exact framing): two deliberately-opposite resolutions — Seam code (dispatcher, lib/, contract) is plugin-dir canonical, project-root fallback; Adapters are consumer-local-first, plugin-bundled fallback, first match wins. Crucially, lib/ is classified as seam code, not adapter code — it resolves as a unit with the dispatcher, never with the adapter that sources it.

Options

(a) Seam-root resolution via the dispatcher's own SCRIPT_DIR — RECOMMENDED.
The dispatcher exports its already-computed seam root; common.sh sources lib/ from that, with the current adapter-relative path kept only as a fallback:

source "${WIT_SEAM_LIB_DIR:-$WIT_GH_ADAPTER_DIR/../../lib}/id.sh"

• Why this beats a ${CLAUDE_PLUGIN_ROOT}-anchored variant: lib/ is seam code, and CONTRACT.md resolves seam code plugin-canonical with a project-root fallback — i.e. the engine legitimately runs from a vendored project-root copy. The dispatcher's $SCRIPT_DIR/lib is definitionally the lib matching whichever engine is actually running (it is the very lib the dispatcher sourced at L12/14/16). ${CLAUDE_PLUGIN_ROOT}/…/lib diverges the moment the engine runs vendored (adapter would load the plugin's lib while the engine runs the vendored one — an id-grammar / lease-format skew), and is unset when no plugin is installed. So exporting SCRIPT_DIR is strictly more correct: it keeps the adapter's lib version-matched to the engine.
• Fallback precedence matters: env-anchor first, adapter-relative fallback — not the reverse. A direct verb invocation (--help, and the adapter unit tests common.test.sh that source common.sh with no dispatcher running) has no export set and must fall back to ../../lib. For the bundled adapter ../../lib == $SCRIPT_DIR/lib, so this is a strict superset of today's behavior and backward-compatible with the existing 29 tests.
• Tradeoffs: simplest; zero consumer burden (a shadow reuses the bundled lib/ untouched); stays fully vendor-agnostic. Cost is one new env export + one changed source line per lib in each adapter.
• Reversibility: high — a purely internal sourcing mechanism, no consumer-facing contract obligation, trivially changed later.

(b) Self-contained / vendored-lib adapters. Each adapter carries the lib helpers it needs, so a shadow is fully portable.

• Tradeoffs: duplicates seam code into every adapter (fights the no-duplication principle); the plugin engine is "read-only and replaced on plugin update," so a vendored/copied lib silently goes stale against an updated engine — breaking id grammar or lease format with no error. Pushes an ongoing sync obligation onto the consumer.
• Reversibility: low — once consumers ship copied libs, walking it back means a coordinated de-vendor.

(c) Documented copy requirement. CONTRACT.md states that shadowing an adapter also requires providing the seam lib/; the exit-3 diagnostic points at that requirement.

• Tradeoffs: cheapest to write (doc-only), but bakes the same lib-drift-on-update failure as (b) into the contract, and puts the entire burden on every consumer who shadows. It codifies the current limitation rather than fixing the root cause.
• Reversibility: low — it is a published contract obligation consumers will build against.

Recommendation

Option (a), seam-root resolution. It is the only option that keeps the adapter's lib/ version-matched to the running engine (honoring CONTRACT.md's "lib/ is seam code" classification and its project-root-fallback), imposes zero consumer burden, stays vendor-agnostic, and is the most reversible. (b)/(c) are both worse (lib drift on plugin update) and less reversible (consumer-facing obligations). Implementation is small: export the seam root from the dispatcher, and change each source line to the ${WIT_SEAM_LIB_DIR:-…/../../lib}/… form (env-first, adapter-relative fallback) in both common.sh files.

Out of scope, noted: the GitHub adapter's WIT_GH_BOT="$WIT_GH_ADAPTER_DIR/../../../github-auth/gh-bot.sh" (github common.sh L37) is the same adapter-relative anti-pattern, already tracked as dependency #2 in #224's medley follow-up — adopting this convention sets a coherent precedent for that sibling fix, but it is not part of this decision.

Per the issue's own acceptance note, whichever option is chosen should update CONTRACT.md "Adapter resolution", apply to both bundled adapters, and add conformance/dispatcher coverage for the consumer-shadow lib-resolution path (the existing throwaway-fixture demo covers shadowing but not this edge).

Cross-link: follow-up from #224 (this is its DESIGN half; the silent-corruption half was fixed in-PR at 9b8ed32).