<?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-21-1-private-teamspace-and-repository-sharing-boundary/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-21-1-private-teamspace-and-repository-sharing-boundary/</id>
  <title>Private Teamspace and Repository Sharing Boundary</title>
  <updated>2026-04-21T00: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-21-1-private-teamspace-and-repository-sharing-boundary/"/>
  <summary>New checkouts belong to a Private Teamspace by default, and a repository is the unit a user explicitly and non-destructively shares into a team.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty’s collaboration model needs a stronger trust boundary than the current “team sees whatever has synced” behavior.&lt;/p&gt;
&lt;p&gt;The product requirement is not merely better filtering. The system must answer two different questions with two different surfaces:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;what repository/build activity belongs to a user privately?&lt;/li&gt;
&lt;li&gt;what repository activity has been intentionally shared into a team?&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The existing product direction around Teamspace and the observed dashboard behavior show a domain mismatch:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;teams can see too many historical projects/builds by default&lt;/li&gt;
&lt;li&gt;users who belong to multiple teams do not have a strong enough routing boundary&lt;/li&gt;
&lt;li&gt;the product vocabulary needs a stable distinction between a shareable repository, a team-facing project, and a build&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Trust boundary first&lt;/strong&gt; — no repository/build data may appear in a team without explicit share and team approval, unless the team explicitly enables auto-approval.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User-owned first&lt;/strong&gt; — data should belong to a user before it becomes team-visible.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Local-first execution&lt;/strong&gt; — build execution and mission progress remain local-first and repository-native.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clear vocabulary&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;repository&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;project&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;build&lt;/code&gt; must describe distinct domain objects.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Active-work emphasis&lt;/strong&gt; — default Teamspace must answer “what is happening now?” rather than act as a historical registry.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; Keep team-owned ingress and improve Teamspace filtering only.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Make repositories opt-in to SaaS globally from the CLI with no user-owned private surface.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3 (chosen):&lt;/strong&gt; User-owned first, &lt;code dir=&quot;auto&quot;&gt;Private Teamspace&lt;/code&gt; by default, explicit repository sharing into teams, and activity-ranked Teamspace surfaces.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: Option 3&lt;/strong&gt;, because it establishes the missing trust boundary while preserving local-first behavior and giving Teamspace a product shape that matches how teams actually work.&lt;/p&gt;
&lt;h3 id=&quot;core-decisions&quot;&gt;Core Decisions&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Decision 1 — New checkouts/builds default to &lt;code dir=&quot;auto&quot;&gt;Private Teamspace&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Every newly observed repository/build belongs to its owning user first. No team sees it until the user explicitly shares the repository into that team.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 2 — &lt;code dir=&quot;auto&quot;&gt;Repository&lt;/code&gt; is the share/admission unit.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The first team admission decision is made for &lt;code dir=&quot;auto&quot;&gt;repository + destination team&lt;/code&gt;. Sharing is explicit and non-destructive: the repository remains visible in &lt;code dir=&quot;auto&quot;&gt;Private Teamspace&lt;/code&gt; after sharing.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 3 — &lt;code dir=&quot;auto&quot;&gt;Project&lt;/code&gt; is the team-facing collaboration surface.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;Project&lt;/code&gt; is created or reused when a repository is shared to a team. It is not the same thing as a local repository or a specific build.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 4 — &lt;code dir=&quot;auto&quot;&gt;Build&lt;/code&gt; remains the checkout/worktree identity.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;Build&lt;/code&gt; is one checkout/worktree on one machine at one local path. &lt;code dir=&quot;auto&quot;&gt;build_id&lt;/code&gt; remains the canonical build key. Machine and absolute local path are required provenance for Teamspace presentation.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 5 — Team approval is one-time per &lt;code dir=&quot;auto&quot;&gt;repository + team&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The first share to a team requires approval unless that team has an explicit auto-approve policy. Once approved, later teammates sharing the same repository into that team join automatically.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 6 — Team disconnect is team-local.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Admin disconnect removes the repository/project from one team’s visibility, search, and discoverable history within that team. It does not delete user-owned data and does not affect other teams.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 7 — Default Teamspace is activity-ranked, not history-ranked.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The default Teamspace project card shows only the 1-3 most relevant &lt;code dir=&quot;auto&quot;&gt;active now&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;recently completed&lt;/code&gt; mission/build items. Historical missions/builds remain discoverable via drilldown/history rather than the landing page.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 8 — GitHub canonicalization ages work off the default surface.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;merged_local_only&lt;/code&gt; may remain discoverable briefly, but once the work is canonicalized on GitHub it leaves the default Teamspace surface and GitHub becomes the canonical inspection point.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Decision 9 — Forks are separate repositories by default.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Forks may expose a visible relationship to upstream, but they do not collapse automatically into the upstream project.&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;Users get a clear safety boundary between private work and team-visible work.&lt;/li&gt;
&lt;li&gt;Teamspace can become a live operational board rather than a project graveyard.&lt;/li&gt;
&lt;li&gt;Vocabulary aligns cleanly: repository for sharing, project for team collaboration, build for checkout.&lt;/li&gt;
&lt;li&gt;The same repository can appear in multiple teams without blurring ownership or disconnect semantics.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The SaaS data model will need migration away from direct team-owned sync materialization assumptions.&lt;/li&gt;
&lt;li&gt;CLI routing UX must become more explicit because the system can no longer assume “sync means team-visible.”&lt;/li&gt;
&lt;li&gt;Approval/disconnect state introduces new operational and testing complexity.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Historical missions/builds still exist and remain discoverable; they simply lose default-surface priority.&lt;/li&gt;
&lt;li&gt;Exact stale-work cleanup policy is deferred; v1 only requires stale work to stay off the default surface.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h2&gt;
&lt;p&gt;This decision is validated when all of the following are true:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;a brand-new checkout/build appears only in the user’s &lt;code dir=&quot;auto&quot;&gt;Private Teamspace&lt;/code&gt; until explicit share&lt;/li&gt;
&lt;li&gt;no team sees repository/build data without explicit share plus approval, unless that team chose auto-approval&lt;/li&gt;
&lt;li&gt;once a repository is approved for a team, later teammates sharing the same repository join automatically&lt;/li&gt;
&lt;li&gt;default Teamspace project cards show only 1-3 relevant active/recent mission/build items&lt;/li&gt;
&lt;li&gt;each surfaced card includes mission progress plus build provenance including machine and local path&lt;/li&gt;
&lt;li&gt;admin disconnect removes visibility from one team only without deleting user-owned data&lt;/li&gt;
&lt;li&gt;canonicalized GitHub work leaves the default Teamspace surface and remains discoverable through history/drilldown&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-keep-team-owned-ingress-and-filter-harder&quot;&gt;Option 1: Keep team-owned ingress and filter harder&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Lowest short-term migration cost.&lt;/li&gt;
&lt;li&gt;Minimal new domain concepts.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Does not create a real trust boundary.&lt;/li&gt;
&lt;li&gt;Keeps Teamspace conceptually backwards.&lt;/li&gt;
&lt;li&gt;Leaves multi-team routing safety weak.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-global-cli-opt-in-without-a-private-surface&quot;&gt;Option 2: Global CLI opt-in without a private surface&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Simple mental model for “send or do not send.”&lt;/li&gt;
&lt;li&gt;Lower SaaS modeling cost than a user-owned first system.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Does not give the product a first-class private collaboration surface.&lt;/li&gt;
&lt;li&gt;Fails the requirement that data should remain visible to the user privately even when not shared to a team.&lt;/li&gt;
&lt;li&gt;Makes governance and discoverability less expressive.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-user-owned-first-with-explicit-sharing&quot;&gt;Option 3: User-owned first with explicit sharing&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Matches the trust and routing requirements.&lt;/li&gt;
&lt;li&gt;Gives Teamspace the right default behavior.&lt;/li&gt;
&lt;li&gt;Supports multi-team participation without collapsing boundaries.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires cross-repo implementation work.&lt;/li&gt;
&lt;li&gt;Introduces new approval/disconnect states and migration needs.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Related planning doc:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-planning/product-ideas/prd-private-teamspace-repository-sharing-and-active-teamspace-v1-2026-04-21.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Related issue:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Priivacy-ai/spec-kitty-saas#99&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;implementation-status-2026-04-21&quot;&gt;Implementation Status (2026-04-21)&lt;/h2&gt;
&lt;p&gt;Status: shipped in &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; commit &lt;code dir=&quot;auto&quot;&gt;de8274f5&lt;/code&gt; and verified against the
deployed &lt;code dir=&quot;auto&quot;&gt;spec-kitty-dev&lt;/code&gt; SaaS environment.&lt;/p&gt;
&lt;p&gt;The current monorepo implementation now reflects this ADR in the CLI layer:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;checkout routing resolves to &lt;code dir=&quot;auto&quot;&gt;Private Teamspace&lt;/code&gt; by default&lt;/li&gt;
&lt;li&gt;repository sharing is explicit through CLI sync commands&lt;/li&gt;
&lt;li&gt;per-checkout opt-in and opt-out persist locally without git-tracked side effects&lt;/li&gt;
&lt;li&gt;future new checkouts can inherit a remembered repository-level sync preference&lt;/li&gt;
&lt;li&gt;routing visibility exposes the owning user/build plus current shared-team state&lt;/li&gt;
&lt;li&gt;opting out can stop ingress immediately and optionally delete already-synced
private-only data after explicit confirmation&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Validation completed for the shipped slice:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;targeted CLI/auth/sync pytest coverage passed (&lt;code dir=&quot;auto&quot;&gt;248 passed&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;targeted Ruff checks passed on the changed CLI/sync surface&lt;/li&gt;
&lt;li&gt;the corresponding SaaS deployment and smoke checks passed on
&lt;code dir=&quot;auto&quot;&gt;https://spec-kitty-dev.fly.dev/&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;current-progress-2026-04-22&quot;&gt;Current Progress (2026-04-22)&lt;/h2&gt;
&lt;p&gt;Status: validated on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;; the CLI lifecycle/migration lane is no longer the
active blocker for the MVP critical path.&lt;/p&gt;
&lt;p&gt;The current monorepo implementation now extends this ADR with the
stale/abandoned mission lane required for the MVP:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;canonical mission lifecycle derivation exists in &lt;code dir=&quot;auto&quot;&gt;specify_cli.status.lifecycle&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;lifecycle.json&lt;/code&gt; is generated alongside other derived mission views&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate normalize-lifecycle&lt;/code&gt; can repair historical
&lt;code dir=&quot;auto&quot;&gt;kitty-specs&lt;/code&gt; missions into the current lifecycle-compatible shape&lt;/li&gt;
&lt;li&gt;a versioned upgrade migration exists to roll that normalization forward&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status lifecycle&lt;/code&gt; exposes the product-facing lifecycle
state directly in the CLI&lt;/li&gt;
&lt;li&gt;targeted CLI lifecycle and migration pytest slices passed on 2026-04-22
(&lt;code dir=&quot;auto&quot;&gt;16 passed&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;the CLI reference docs now include both &lt;code dir=&quot;auto&quot;&gt;migrate normalize-lifecycle&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;agent status lifecycle&lt;/code&gt;, so the upgrade/inspection path is discoverable to
users&lt;/li&gt;
&lt;li&gt;the sync hardening needed to trust this lifecycle lane in SaaS is already on
&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;:
zero-byte dossier placeholders are skipped, queue scoping follows the
encrypted auth session, and permanent upload failures persist structured
diagnostics instead of collapsing to &lt;code dir=&quot;auto&quot;&gt;bad_request: unknown&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;With this slice validated, the active MVP lane moves back to SaaS Teamspace
projection/backfill completion under &lt;code dir=&quot;auto&quot;&gt;Priivacy-ai/spec-kitty-saas#101&lt;/code&gt;.&lt;/p&gt;</content>
</entry>
