Implementation Logger

# Create implementation log
echo "# Implementation Log: [Feature Name]" > .implementation-log.md
echo "" >> .implementation-log.md
echo "Started: $(date)" >> .implementation-log.md
echo "" >> .implementation-log.md
echo "## Original Plan" >> .implementation-log.md
echo "[Brief summary of approach]" >> .implementation-log.md
echo "" >> .implementation-log.md
echo "## Deviations & Decisions" >> .implementation-log.md

### [Timestamp] - [Decision Point Title]

**Context**: What I encountered that wasn't in the plan

**Original Assumption**: What I thought would work

**Reality**: What I actually found

**Decision**: What I decided to do instead

**Rationale**: Why this approach is better/necessary

**Impact**: What else this might affect

# Implementation Log: [Feature Name]

**Date**: [Date]
**Developer**: [Name or Agent ID]
**Original Plan**: [Link to spec/plan]

## Summary
[One paragraph: what we built and key decisions]

## Original Approach
[What we planned to do]

## Deviations & Decisions

### Decision 1: [Title]
**When**: [Timestamp/phase]
**Context**: [What prompted this decision]
**Original Plan**: [What we thought we'd do]
**Reality**: [What we actually found]
**Decision**: [What we decided]
**Rationale**: [Why this is better]
**Impact**: [Side effects or dependencies]
**Code**: [Link to relevant commit/files]

### Decision 2: [Title]
...

## Unknowns Discovered

### Unknown: [Title]
**Category**: [Architecture/Spec/Technical/Business]
**Impact**: [High/Medium/Low]
**Description**: [What we didn't know]
**Resolution**: [How we resolved it]
**Future Consideration**: [Should this inform future work?]

## Learnings

### What Worked Well
- [Learning 1]
- [Learning 2]

### What Was Surprising
- [Surprise 1]
- [Surprise 2]

### What to Do Differently Next Time
- [Improvement 1]
- [Improvement 2]

## Documentation Updates Needed
- [ ] Update ADR on [topic]
- [ ] Add to MEMORY.md: [learning]
- [ ] Update [skill/guide]: [improvement]

## Follow-up Questions
1. [Question that arose during implementation]
2. [Question for stakeholder/team]

# Implementation Log: GitHub OAuth Integration

**Date**: 2026-07-08
**Original Plan**: docs/specs/github-oauth.md

## Summary
Implemented GitHub OAuth provider following existing OAuth pattern.
Key deviation: Used App Installation flow instead of user OAuth due to
org-level permission requirements. Added webhook endpoint for
installation events.

## Original Approach
- Implement standard OAuth 2.0 flow via library
- Use Personal Access Token (PAT) flow for initial testing

## Deviations & Decisions

### Decision 1: Use GitHub App Installation Flow

**When**: During initial auth flow implementation

**Context**: Testing revealed that org-level repo access requires GitHub
App installation, not user OAuth. Our target users need org repo access.

**Original Plan**: Standard OAuth with PAT

**Reality**: GitHub deprecated PAT for org access. Apps must use
Installation flow which requires:
- App installation per organization
- Installation webhook handling
- Installation-specific tokens

**Decision**: Implement GitHub App Installation flow instead

**Rationale**:
- Only way to get org-level repo access
- More secure (granular permissions)
- Better aligned with GitHub's current best practices
- Matches what users expect (seen in other tools)

**Impact**:
- Added webhook endpoint: /webhooks/github/installation
- New database table: github_installations
- Installation token refresh logic (expires after 1hr vs 6mo)
- More complex setup docs (users must create GitHub App)

**Code**: commit abc123, files: auth/github/installation.ts

### Decision 2: Cache Installation Tokens

**When**: During token refresh implementation

**Context**: Installation tokens expire after 1 hour. Naive approach would
request new token for every API call.

**Original Plan**: Request new token on each API call

**Reality**: GitHub rate limits token requests to 5000/hour per app.
With multiple users in same org, we'd hit limit quickly.

**Decision**: Cache installation tokens in Redis with 55min TTL

**Rationale**:
- Prevents rate limit issues
- Reduces latency (no token request per API call)
- 55min TTL provides 5min safety buffer before expiry
- Existing Redis used for other caching

**Impact**:
- Added Redis key pattern: github:install:{id}:token
- Token refresh logic checks cache first
- Cache invalidation on installation webhook events

**Code**: commit def456, files: auth/github/token-cache.ts

### Decision 3: Handle Installation Deletion

**When**: Writing webhook handler

**Context**: Users can uninstall the GitHub App from their org

**Original Plan**: Not explicitly considered

**Reality**: Installation deletion is common (users test, revoke, etc).
Must handle gracefully.

**Decision**: Soft-delete installations, preserve audit log

**Rationale**:
- Maintain audit trail of access history
- Prevent orphaned references in user sessions
- Allow re-installation without data loss
- Compliance requirement (track who had access when)

**Impact**:
- Added `deleted_at` column to github_installations
- Webhook handler for installation.deleted event
- Session middleware checks installation.deleted_at
- User sees clear error: "GitHub integration removed"

**Code**: commit ghi789, files: webhooks/github.ts

## Unknowns Discovered

### Unknown: GitHub App vs OAuth App
**Category**: Architecture
**Impact**: High
**Description**: Didn't realize GitHub has two different app types with
different capabilities. OAuth Apps can't get org-level repo access.
**Resolution**: Used GitHub App with Installation flow
**Future Consideration**: Document this in our OAuth integration guide.
Other providers may have similar dual-model systems.

### Unknown: Installation Token Lifespan
**Category**: Technical
**Impact**: Medium
**Description**: Installation tokens expire after 1 hour, not 6 months
like user tokens. This wasn't in our initial spec.
**Resolution**: Implemented caching strategy
**Future Consideration**: Standard pattern for short-lived tokens?

### Unknown: Rate Limit on Token Requests
**Category**: Technical
**Impact**: Medium
**Description**: Token endpoint has its own rate limit separate from API
**Resolution**: Cache tokens in Redis
**Future Consideration**: Consider for other OAuth providers too

## Learnings

### What Worked Well
- Blind spot pass identified existing OAuth pattern to follow
- Webhook infrastructure was already in place
- Redis caching pattern from other auth providers was reusable

### What Was Surprising
- GitHub's dual app model (wasn't in initial research)
- How common installation deletion is (users test a lot)
- Token request rate limiting (separate from API limits)

### What to Do Differently Next Time
- Research provider-specific gotchas more deeply upfront
- Ask explicitly about token lifespan in spec interview
- Consider short-lived tokens in architecture discussions

## Documentation Updates Needed
- [x] Add to skills/blindspot-pass examples: Check for dual auth models
- [ ] Update MEMORY.md: GitHub Apps vs OAuth Apps distinction
- [ ] Create ADR: Short-lived token caching strategy
- [ ] Update OAuth integration guide with GitHub App specifics

## Follow-up Questions
1. Should we implement GitHub App for user-level access too (consistency)?
2. Do other OAuth providers have similar dual models to document?
3. Should Redis cache TTL be configurable per provider?