Auto-notifications for KB Updates

[rucka]

Story Statement

As a developer using pair CLI
I want to receive automatic notifications when organizational KB updates are available
So that I stay current with organizational standards without manually checking

Where: pair CLI — non-intrusive banner on any pair command execution

Epic Context

Parent Epic: CLI Knowledge-Service Integration #67
Status: Refined
Priority: P1 (Should-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 org KB v1.0.0 is installed and v1.2.0 is available
   When the developer runs any pair command and the last check was >24h ago
   Then after command output, a banner appears: "Org KB update available: v1.0.0 → v1.2.0. Run pair kb update --org acme"

2. Given org KB is up to date
   When the developer runs any pair command
   Then no banner is shown

3. Given the developer is in a non-interactive terminal (CI/CD)
   When any pair command runs
   Then no update check or banner is shown

4. Given the developer sets PAIR_NO_UPDATE_CHECK=1 or --no-update-check flag
   When any pair command runs
   Then no update check or banner is shown

5. Given the check interval has not elapsed since the last check
   When the developer runs a pair command
   Then no network request is made (use cached result); banner shown only if cached result indicates update available

Business Rules

• Check interval: configurable, default 24 hours
• Check result cached in ~/.pair/cache/update-check.json: { "acme": { "latest": "1.2.0", "checked_at": "..." } }
• Banner appears AFTER command output (never interrupts primary command)
• Banner uses stderr (not stdout) to avoid polluting piped output
• Suppression: non-interactive terminal, PAIR_NO_UPDATE_CHECK=1, --no-update-check
• Check is async (non-blocking) — uses cached result, triggers background check for next time
• Maximum 1 banner per command execution (even with multiple orgs)

Edge Cases and Error Handling

• Network error during background check: Silently fail, use stale cache
• No orgs configured: No check, no banner
• Cache file missing: Trigger fresh check, no banner this time
• Multiple orgs with updates: Show one combined banner listing all orgs with updates
• Service returns unexpected response: Silently fail, use cached data

Definition of Done Checklist

Development Completion

• All 5 acceptance criteria implemented and verified
• Background check with caching
• Non-intrusive banner on stderr
• Suppression via env var, flag, and TTY detection
• Unit tests for check logic, caching, suppression
• Integration tests for banner display

Quality Assurance

• Update check adds 0ms latency to command execution (async/cached)
• Banner never appears in piped output (stderr only)
• Suppression works for all three methods

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: L(5)
Confidence Level: Medium
Sizing Justification: Background check mechanism, caching layer, TTY detection, banner UX on stderr, suppression modes. Non-trivial async coordination but well-scoped.

Sprint Capacity Validation

Sprint Fit Assessment: Fits in single sprint
Total Effort Assessment: Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #158 (Update — version check logic), #160 (Status — version comparison)
Dependent Stories: None

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: Unit tests for cache management, TTY detection, suppression; integration tests for banner display in various scenarios
Test Data Requirements: Various cache states, TTY/non-TTY environments
Environment Requirements: TTY mocking, mock HTTP server

Notes

Refinement Insights: The key UX decision is "after command output on stderr" — never interrupt, never pollute stdout.

Technical Analysis

Implementation Approach

Technical Strategy: CLI bootstrap hook that runs after main command completes. Reads cache, if stale triggers async HTTP check (fire-and-forget for next invocation). Displays banner from cache if update available. All output to stderr.
Key Components: Update check hook (CLI post-command), cache manager, banner formatter, suppression logic
Data Flow: CLI bootstrap → read cache → if fresh + update available → banner on stderr. In background: → check stale? → async fetch latest → update cache

Technical Requirements

• Cache: ~/.pair/cache/update-check.json with per-org entries
• Async check: setTimeout(() => fetch(...).then(updateCache), 0) — non-blocking
• Banner: process.stderr.write(chalk.yellow(...)) — after main command output
• TTY: process.stdout.isTTY (already used in CLI per ADR-001)
• Suppression: check PAIR_NO_UPDATE_CHECK env + --no-update-check global flag

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Background check outlives CLI process	Low	Medium	Use process.on('beforeExit') or detached child process for network call

Spike Requirements

Required Spikes: None