<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-04-06-2-connector-auth-binding-separation/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-06-2-connector-auth-binding-separation/</id>
  <title>ADR: Connector Installation, User Link, and Resource Mapping Separation</title>
  <updated>2026-04-06T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-04-06-2-connector-auth-binding-separation/"/>
  <summary>Accepted ADR separating connector installation, user link, and resource mapping, replacing the per-binding OAuth-token storage in ConnectorBinding.</summary>
  <content type="html">&lt;span id=&quot;adr-connector-installation-user-link-and-resource-mapping-separation&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Status&lt;/strong&gt;: Accepted
&lt;strong&gt;Date&lt;/strong&gt;: 2026-03-10
&lt;strong&gt;Author&lt;/strong&gt;: Spec Kitty team + Claude + Codex
&lt;strong&gt;Supersedes&lt;/strong&gt;: Implicit design in &lt;code dir=&quot;auto&quot;&gt;ConnectorBinding&lt;/code&gt; where OAuth tokens are stored per-binding&lt;/p&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;The current connector models conflate multiple concerns into one record:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Provider installation / workspace connection&lt;/strong&gt;: the act of connecting Spec-Kitty to a provider boundary such as a GitHub organization install, Jira site, Linear workspace, or Slack workspace&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User account linkage&lt;/strong&gt;: the optional association of an individual member with that provider for identity mapping, acting-as-user flows, or personal automations&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Resource routing&lt;/strong&gt;: the mapping of external resources such as repos, Jira projects, Linear teams, or Slack channels to Spec-Kitty projects or feeds&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Project-specific policy&lt;/strong&gt;: doctrine and routing overrides that only matter for exceptional projects&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;ConnectorBinding&lt;/code&gt; stores OAuth credentials directly on a project-scoped binding. This forces users to pick a project before they have even connected the service, which is a UX antipattern and a domain mismatch.&lt;/p&gt;
&lt;p&gt;More importantly, the model is not provider-native:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;GitHub Apps are installed on a personal account or organization and may be scoped to selected repositories.&lt;/li&gt;
&lt;li&gt;Slack apps are installed to a workspace, then often configured per-channel.&lt;/li&gt;
&lt;li&gt;Jira and Linear integrations are typically authorized at a site/workspace boundary, then configured for projects or teams underneath that.&lt;/li&gt;
&lt;li&gt;Some member-specific behaviors still require per-user links after the workspace installation exists.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The project selector on the connector creation page is therefore a symptom of a deeper problem: Spec-Kitty treats all integrations as user-level OAuth credentials when the dominant industry pattern is to separate installation, optional user linking, resource mapping, and project policy.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Workspace installation is the primary connector boundary. User links are optional. Resource mappings are explicit. Project overrides are exceptional.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;In current product terms, “workspace” maps to the existing &lt;code dir=&quot;auto&quot;&gt;Team&lt;/code&gt; model.&lt;/p&gt;
&lt;h3 id=&quot;four-layer-model&quot;&gt;Four-layer model&lt;/h3&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Layer 1: Team Service Installation (workspace-level)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;&quot;Spec-Kitty workspace Acme Engineering is connected to GitHub / Jira / Slack / Linear&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Owns the provider installation or admin-authorized workspace/site connection&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Created from the Connectors page&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- No project selection during installation&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Scoped to the current Team model&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Layer 2: User Service Link (optional, user-level)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;&quot;Bob has linked his GitHub / Jira account to the existing workspace installation&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Used for identity mapping, assignee sync, acting-as-user flows, and personal automations&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Not required for baseline webhook routing or shared workspace setup&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Multiple users can link to the same workspace installation&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Layer 3: Service Resource Mapping (team-level)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;&quot;Repo acme/backend maps to project acme-backend&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;&quot;Jira project ACME maps to project acme-backend&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;&quot;Slack channel #frontend-alerts maps to project acme-frontend&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Routes provider resources into Spec-Kitty&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Can target a project or another workspace-level feed, depending on provider&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Created explicitly, even when auto-suggested&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Layer 4: Project Service Policy Override (project-level, optional)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;&quot;Project acme-frontend uses split_ownership for Jira&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Overrides workspace defaults only when needed&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Holds doctrine and provider-specific exception policy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;- Most projects should inherit defaults&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;service-specific-routing-model&quot;&gt;Service-specific routing model&lt;/h3&gt;















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Service&lt;/th&gt;&lt;th&gt;Primary installation scope&lt;/th&gt;&lt;th&gt;User link needed?&lt;/th&gt;&lt;th&gt;Resource mapping&lt;/th&gt;&lt;th&gt;Notes&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;GitHub&lt;/td&gt;&lt;td&gt;Team/workspace installation, ideally GitHub App or org-level connection&lt;/td&gt;&lt;td&gt;Optional&lt;/td&gt;&lt;td&gt;Repo → Spec-Kitty project&lt;/td&gt;&lt;td&gt;Auto-suggest from commit graph and git remotes, manual fallback&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;GitLab&lt;/td&gt;&lt;td&gt;Team/workspace installation&lt;/td&gt;&lt;td&gt;Optional&lt;/td&gt;&lt;td&gt;Repo/group resource → Spec-Kitty project&lt;/td&gt;&lt;td&gt;Same as GitHub&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Jira&lt;/td&gt;&lt;td&gt;Team/workspace installation for site/workspace&lt;/td&gt;&lt;td&gt;Optional&lt;/td&gt;&lt;td&gt;Jira project → Spec-Kitty project&lt;/td&gt;&lt;td&gt;Manual mapping required&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Linear&lt;/td&gt;&lt;td&gt;Team/workspace installation for workspace&lt;/td&gt;&lt;td&gt;Optional&lt;/td&gt;&lt;td&gt;Linear team/project → Spec-Kitty project&lt;/td&gt;&lt;td&gt;Manual mapping required&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Slack&lt;/td&gt;&lt;td&gt;Team/workspace installation for workspace&lt;/td&gt;&lt;td&gt;Optional&lt;/td&gt;&lt;td&gt;Channel → project/team feed/incident stream&lt;/td&gt;&lt;td&gt;Channel routing is first-class&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;git-native-mapping-is-an-auto-suggestion-not-the-sole-source-of-truth&quot;&gt;Git-native mapping is an auto-suggestion, not the sole source of truth&lt;/h3&gt;
&lt;p&gt;For GitHub and GitLab, Spec-Kitty already has strong signals from the CLI sync:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Local git remotes observed from CLI usage&lt;/li&gt;
&lt;li&gt;Commit SHAs present in synced builds&lt;/li&gt;
&lt;li&gt;Branch names and &lt;code dir=&quot;auto&quot;&gt;feature_slug&lt;/code&gt; values in namespaces&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;These signals should be used to &lt;strong&gt;suggest&lt;/strong&gt; or &lt;strong&gt;auto-create&lt;/strong&gt; repo mappings in the common case. They should not replace explicit installation and mapping records.&lt;/p&gt;
&lt;p&gt;Webhook routing order:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Use explicit &lt;code dir=&quot;auto&quot;&gt;ServiceResourceMapping&lt;/code&gt; if present&lt;/li&gt;
&lt;li&gt;Fall back to commit-graph and remote heuristics for unmatched git events&lt;/li&gt;
&lt;li&gt;Queue unmatched events for review when the system cannot resolve confidently&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This preserves the low-friction Git experience without pretending that commit metadata alone is a complete connector model.&lt;/p&gt;
&lt;h3 id=&quot;slack-is-not-a-special-case-that-avoids-mapping&quot;&gt;Slack is not a special case that avoids mapping&lt;/h3&gt;
&lt;p&gt;Slack does not map naturally to a single Spec-Kitty project, but it still needs resource routing. The routing unit is usually a &lt;strong&gt;channel&lt;/strong&gt;, not a workspace:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Workspace install happens once&lt;/li&gt;
&lt;li&gt;Channels can then be mapped to project notifications, team-wide feeds, or incident streams&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This matches the natural Slack mental model better than “team-level only, no project mapping.”&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Provider-native design&lt;/strong&gt;: matches how GitHub Apps, Slack apps, Jira, and Linear are actually installed and configured&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unblocked onboarding&lt;/strong&gt;: the first user can install services before project-by-project setup exists&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cleaner admin model&lt;/strong&gt;: workspace installations belong to the workspace, not to a single person’s project-scoped token&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cleaner member onboarding&lt;/strong&gt;: new members can use existing installations immediately and only link their account if needed&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cleaner offboarding&lt;/strong&gt;: deactivating one member’s user links does not tear down the shared workspace installation&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Explicit routing&lt;/strong&gt;: repo/project/channel mappings become first-class state instead of hidden assumptions&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Better Slack model&lt;/strong&gt;: channel mapping becomes a supported concept instead of an awkward exception&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;More connector concepts&lt;/strong&gt;: installation, user link, resource mapping, and override are more precise but more numerous than a single binding record&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Provider-specific UX&lt;/strong&gt;: the install flow will differ across providers because the providers differ&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Migration required&lt;/strong&gt;: existing binding records with embedded OAuth credentials must be split across the new layers&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;More routing records&lt;/strong&gt;: GitHub/GitLab repo mappings become explicit records even when discovered automatically&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;IssueTrackerBinding&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;UserProviderConnection&lt;/code&gt; already hint at the right separation, but they still attach the user credential too closely to a project binding&lt;/li&gt;
&lt;li&gt;Commit-graph routing remains valuable, but as an inference tool and fallback, not as the primary authority&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;h3 id=&quot;option-a-purely-user--service-no-routing-layer&quot;&gt;Option A: Purely user → service, no routing layer&lt;/h3&gt;
&lt;p&gt;Rejected. Non-git providers need resource routing, and even git providers benefit from explicit repo mappings for auditability and recovery.&lt;/p&gt;
&lt;h3 id=&quot;option-b-user-level-auth-project-level-binding&quot;&gt;Option B: User-level auth, project-level binding&lt;/h3&gt;
&lt;p&gt;Rejected as the primary model. It matches deploy tools like Vercel and Netlify for single-project git flows, but it does not generalize to Slack workspace installs, GitHub App installation scope, or shared Jira/Linear workspace setup.&lt;/p&gt;
&lt;p&gt;Retained as the override mechanism for exceptional project-specific policy.&lt;/p&gt;
&lt;h3 id=&quot;option-c-team-level-binding-only-no-user-links&quot;&gt;Option C: Team-level binding only, no user links&lt;/h3&gt;
&lt;p&gt;Rejected as the sole model. Member-specific capabilities such as identity mapping, acting-as-user, and personal automation need an optional user-level association.&lt;/p&gt;
&lt;h3 id=&quot;option-d-commit-graph-as-the-only-routing-authority-for-git-services&quot;&gt;Option D: Commit graph as the only routing authority for git services&lt;/h3&gt;
&lt;p&gt;Rejected. Commit data is an excellent signal but an incomplete authority. Brand-new repos, mono-repos, and provider permission boundaries still require explicit installation and mapping state.&lt;/p&gt;
&lt;h2 id=&quot;industry-precedents&quot;&gt;Industry precedents&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Vercel / Netlify&lt;/strong&gt;: user connects a git provider, then links a specific repository to a specific project. Good precedent for Git-native project linking, but too narrow as a universal connector model.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Sentry&lt;/strong&gt;: installs integrations at the organization level, then configures project-level alerting, code mappings, and issue creation beneath that.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Linear&lt;/strong&gt;: separates organization connection, account connection, and team workflow automation in its GitHub integration.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Slack + PagerDuty&lt;/strong&gt;: workspace installation first, then channel/service linking, plus optional user account linking.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;GitHub Apps&lt;/strong&gt;: installation happens on a user or organization boundary and can be restricted to selected repositories.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;These products converge on the same pattern: installation scope first, user links when needed, resource mapping second, project policy last.&lt;/p&gt;
&lt;h2 id=&quot;related&quot;&gt;Related&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Companion planning artifact: &lt;code dir=&quot;auto&quot;&gt;prd-connector-auth-first-team-binding-v1.md&lt;/code&gt; in the planning repo&lt;/li&gt;
&lt;li&gt;Existing tracker interface PRD: &lt;code dir=&quot;auto&quot;&gt;prd-universal-task-tracker-interface-and-doctrine-sot-v1.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Current models: &lt;code dir=&quot;auto&quot;&gt;apps/connectors/models.py&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;reference-links&quot;&gt;Reference links&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://vercel.com/docs/git/vercel-for-github&quot;&gt;Vercel Git integration docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.netlify.com/start/add-new-project/&quot;&gt;Netlify import existing project&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.sentry.io/organization/integrations/issue-tracking/jira/&quot;&gt;Sentry Jira integration docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.sentry.io/organization/integrations/notification-incidents/msteams/&quot;&gt;Sentry Microsoft Teams integration docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://linear.app/docs/github-integration&quot;&gt;Linear GitHub integration docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.slack.dev/app-management/distribution/&quot;&gt;Slack app lifecycle and distribution docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://support.pagerduty.com/main/docs/slack-integration-guide&quot;&gt;PagerDuty Slack integration guide&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app&quot;&gt;GitHub App installation docs&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
