Investigation: multi-provider topology — source-of-record + coordination split

[kyle-sexton]

Parent

Refs #2933. Source: topic pocock-shipping-breakdown (PR backfilled when opened). Investigation item — resolves a decision, produces no production code. Evidence: topic memory slice seam-scrutiny-findings.md (F3.1, F3.2, F3.9).

What to decide

The binding permits exactly ONE provider, which forecloses the motivating real-world topology: an org tracker (e.g. Jira) as read-only source of record + a separate agentic coordination surface (GitHub, Linear) that agents may write to without polluting the org backlog. Scrutiny established: the fully-qualified ID grammar already routes id-taking verbs nearly for free; the hard parts are id-less verbs (frontier/create need --provider scoping or merged-envelope semantics), cross-provider blocking edges (necessarily text pointers, not native), and leases/labels staying coordination-provider-only. Also in scope:

• GitHub PR/issue shared-numbering (F3.2): agentic issues inflate PR numbers; every avoidance topology (issues-only repo via --repo, different provider, local-markdown) currently collides with a load-bearing mechanic (Closes #N same-repo linkage, open-PR frontier check, sub-issue cross-repo truncation, CWD-derived repo default). Decide the supported topology (or topologies) and what each costs.
• F3.9: the --repo override exists at the seam but no skill surface plumbs it — the skill layer can't express what the seam supports.
• Binding schema direction: second source key vs role-typed provider list (e.g. coordination + sources[]).

Output: a decision recorded as a closing comment (and ADR if warranted), unblocking the Jira-write item and shaping the Linear/issues-only-repo paths.

Acceptance criteria

• Supported topology decision recorded with trade-offs, including the PR-numbering answer
• Binding-schema direction chosen (or explicitly deferred with a trigger)
• Follow-on build items filed per the decision

Blocked by

None — can start immediately.

[kyle-sexton]

Resolved: role-split topology — one writable coordination provider, N read-only sources. (Interview 2026-08-17, maintainer accepted all recommendations; evidence: seam-scrutiny F3.1/F3.2/F3.9 archived on #2933.)

1. Binding schema direction: keep provider as THE coordination surface (exactly one; unchanged semantics — owns create/claim/lease/frontier/edges). Add an optional sources: [...] array of read-only providers feeding reads (decompose ingesting an epic, triage resolving a referenced ticket). There is never a second writable surface — the F1.4 race-safety rule stays structural. Rejected: single source key (blocks multi-source for no savings); general role-tagged provider list (no third role exists).
2. Verb routing: id-taking verbs route by the qualified ID's provider prefix (grammar already supports it); id-less verbs stay coordination-bound; source reads reachable via explicit --provider <name> on get-item/list-items only. No merged frontiers, ever — the frontier remains a coordination-provider derivation.
3. Provenance: one-way, coordination-side text pointers (Source: jira:site/KEY#n in the item body); nothing is written back to a source — read-only IS the anti-pollution guarantee. Documented as a text link, never a native edge.
4. PR/issue shared-numbering (F3.2): the supported answer is a different coordination provider (concretely Linear, once Linear adapter with full verb parity #2946 lands). The issues-only-second-GitHub-repo topology is REJECTED with recorded costs (breaks Closes #N same-repo linkage, the open-PR frontier check, and sub-issue cross-repo truncation) — unsupported-until-requested.
5. Consequences: Jira write support — guarded, opt-in #2951 (Jira write) is superseded — under this model Jira's value is its read-only-ness; any future status-sync-back is a new demand-gated design. Linear adapter with full verb parity #2946 (Linear) gains its sharpened mission: reference coordination provider for the split topology and the PR-numbering answer. F3.9's --repo skill plumbing is rejected for now (the split makes it unnecessary). Maintainer probe answered implicitly: no current need for agents writing Jira status back.

Implementation of the sources schema is demand-gated — it lands with its first consumer (most plausibly a decompose ingest of a real source epic), not speculatively. Closing this investigation item: its deliverable was this decision.

---

Generated by Claude Code