Multi-Organization KB Sources

[rucka]

Story Statement

As a developer working across multiple organizations or teams
I want to manage KB content from multiple organizational sources simultaneously
So that I can access standards from different teams or projects without switching contexts

Where: pair CLI — pair kb command family with multi-org support

Epic Context

Parent Epic: CLI Knowledge-Service Integration #67
Status: Refined
Priority: P2 (Could-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

1. Given a developer has configured two orgs "acme" and "globex"
   When they run pair kb list-orgs
   Then the CLI prints a table: org name, endpoint, installed version, auth status for each

2. Given two orgs are configured
   When the developer runs pair kb install --org acme then pair kb install --org globex
   Then KB content is installed in org-namespaced directories: .pair/orgs/acme/ and .pair/orgs/globex/

3. Given two org KBs are installed
   When the developer runs pair kb switch-org acme
   Then the CLI symlinks .pair/active-org → .pair/orgs/acme/ and prints "Active org: acme. Skills and guidelines from acme are now active."

4. Given the developer wants to remove an org
   When they run pair kb remove-org globex
   Then the CLI removes .pair/orgs/globex/, associated credentials, config, and prints "Removed org 'globex' and its local KB content"

5. Given two orgs have overlapping skill names (e.g., both provide commit skill)
   When the developer switches org
   Then the active org's skills take precedence; the CLI warns "Skill 'commit' exists in both acme and globex. Using acme (active org)."

Business Rules

• Org KB namespacing: .pair/orgs/<org-name>/ per org
• Active org: .pair/active-org symlink points to active org directory
• Only one active org at a time (skill distribution targets use active org content)
• switch-org updates the symlink and re-distributes skills to tool directories
• Credentials and config remain per-org (already supported by CLI Authentication with Knowledge Service #156 and Configure Org KB Sources in CLI #159)
• list-orgs shows all configured orgs regardless of install state

Edge Cases and Error Handling

• No orgs configured: "No organizations configured. Run pair kb config set first."
• Switch to non-installed org: "Org 'xyz' is not installed. Run pair kb install --org xyz first."
• Remove active org: Switch to another org first or set no active org; warn "Cannot remove active org. Switch to another org first."
• Symlink not supported (Windows): Use junction point or copy fallback with warning
• Single-org upgrade: If existing .pair/ has non-namespaced KB, auto-migrate to .pair/orgs/<detected-org>/ on first multi-org operation

Definition of Done Checklist

Development Completion

• All 5 acceptance criteria implemented and verified
• Org namespacing in .pair/orgs/
• switch-org with symlink management
• list-orgs command
• remove-org with cleanup
• Conflict detection for overlapping skills
• Migration from single-org to multi-org layout
• Unit tests for namespace management and switching
• Integration tests for multi-org workflow

Quality Assurance

• Symlink creation works on macOS and Linux
• Windows fallback (junction/copy) tested
• Migration preserves existing KB content
• Skill distribution reflects active org

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: XL(8)
Confidence Level: Low
Sizing Justification: Namespace management, symlink-based switching, migration from single to multi-org, conflict detection, cross-platform symlink handling. Highest uncertainty in the epic.

Sprint Capacity Validation

Sprint Fit Assessment: Tight for single sprint
Total Effort Assessment: Borderline

Story Splitting Recommendations

1. Multi-Organization KB Sources #162-A: Org namespacing + list-orgs + install to namespace (L(5))
2. Multi-Organization KB Sources #162-B: switch-org + skill redistribution + conflict detection + migration (M(3))

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: All P0 stories (#156, #157, #158, #159) — multi-org extends single-org patterns
Dependent Stories: None

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: Integration tests for full multi-org workflow; unit tests for namespace management, symlink creation, conflict detection
Test Data Requirements: Two sample KB packages with overlapping and non-overlapping content
Environment Requirements: Temp directories for namespace tests

Notes

Refinement Insights: The single-to-multi-org migration is the riskiest part. Consider designing #157 (Install) with namespace support from the start (even if single-org uses it transparently).

Technical Analysis

Implementation Approach

Technical Strategy: Refactor install to always use .pair/orgs/<name>/ namespace. Add symlink .pair/active-org → .pair/orgs/<name>/. Skill distribution reads from active-org symlink. Migration detects non-namespaced .pair/ and auto-migrates.
Key Components: Namespace manager, symlink manager (cross-platform), org switcher, migration tool, conflict detector
Data Flow: Install → .pair/orgs// → switch → update symlink → re-distribute skills

Technical Requirements

• Directory layout: .pair/orgs/<org-name>/<kb-content>, .pair/active-org → .pair/orgs/<name>/
• Symlink: fs.symlink(target, '.pair/active-org', 'junction') — junction for Windows compat
• Migration: detect .pair/.kb-meta.json without orgs/ structure → move to .pair/orgs/<org>/
• Conflict detection: compare skill manifest across orgs, warn on duplicates

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Migration corrupts existing KB	High	Low	Backup before migration; validate after; rollback on failure
Windows junction points require admin	Medium	Medium	Detect and fall back to copy mode with warning
Skill distribution coupling with active-org	Medium	Medium	Ensure skill distribution always reads from symlink target, not hardcoded path

Spike Requirements

Required Spikes: Test symlink/junction behavior on Windows CI environment