feat: Add ADR timeline tracking with context-aware analysis

Implements comprehensive timeline tracking for ADRs with intelligent
context detection and automated action item generation.

New Features:
- Multi-source timeline extraction (git → content → filesystem)
- Smart conditional logic to minimize expensive operations
- In-memory caching for performance
- Project context detection (startup/growth/mature/maintenance)
- Adaptive threshold profiles based on project phase
- ADR type modifiers (infrastructure/security/refactoring/feature)
- Automated action item generation with urgency scoring
- New MCP tool: analyze_adr_timeline

Implementation Details:
- Created 4 new utility modules for timeline features
- Updated discoverAdrsInDirectory signature (breaking change)
- Fixed 31 TypeScript compilation errors
- Integrated timeline into ADR discovery system
- Added ADR-011 documenting the feature

Technical Notes:
- Implemented separate in-memory cache (cache.ts is prompt-driven)
- All threshold profiles configurable and overridable
- Context auto-detection using git activity analysis
- Timeline extraction fallback chain ensures data availability

Files Added:
- src/utils/adr-timeline-extractor.ts
- src/utils/adr-context-detector.ts
- src/utils/adr-action-analyzer.ts
- src/utils/adr-timeline-types.ts
- docs/adrs/adr-011-adr-timeline-tracking-and-context-aware-analysis.md

Files Modified:
- src/index.ts (added analyze_adr_timeline tool + fixed ESLint)
- src/utils/adr-discovery.ts (integrated timeline)
- 20+ files updated for new discoverAdrsInDirectory signature

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: tosin2013

docs/adrs/adr-011-adr-timeline-tracking-and-context-aware-analysis.md

@@ -0,0 +1,213 @@
+# ADR-011: ADR Timeline Tracking and Context-Aware Analysis
+
+## Status
+Accepted
+
+## Date
+2025-11-19
+
+## Context
+
+As our ADR analysis server matured, we identified several limitations in how we track and analyze architectural decisions:
+
+1. **No Temporal Awareness**: The system couldn't track when decisions were made or how long they've been in various states
+2. **Missing Staleness Detection**: No way to identify outdated or neglected ADRs that need attention
+3. **Context-Agnostic Thresholds**: Same staleness thresholds applied to all projects (startup vs. enterprise)
+4. **Manual Action Planning**: Users had to manually identify which ADRs need updates or implementation
+5. **Performance Concerns**: Extracting timeline data could be expensive without smart caching
+
+## Decision
+
+We implemented a comprehensive ADR Timeline Tracking system with the following components:
+
+### 1. Timeline Extraction (src/utils/adr-timeline-extractor.ts)
+
+**Multi-Source Timeline Extraction**:
+- **Git History** (preferred): Extract creation/update dates from git log
+- **Content Parsing** (fallback): Parse date fields from ADR content
+- **Filesystem** (last resort): Use file modification times
+
+**Smart Conditional Logic**:
+- Only extract when necessary (no timestamp in content, file modified, cache miss)
+- In-memory caching to avoid repeated expensive operations
+- Configurable force-extract option for manual overrides
+
+**Timeline Data Structure**:
+```typescript
+interface BasicTimeline {
+  created_at: string;        // ISO timestamp
+  updated_at: string;        // ISO timestamp
+  age_days: number;          // Days since creation
+  days_since_update: number; // Days since last modification
+  staleness_warnings: string[]; // Generated warnings
+  extraction_method: 'git' | 'content' | 'filesystem';
+}
+```
+
+### 2. Project Context Detection (src/utils/adr-context-detector.ts)
+
+**Automatic Project Phase Detection**:
+- **Startup**: High commit rate (>50/week), frequent ADRs (>3/month)
+- **Growth**: Moderate commits (20-50/week), regular ADRs (>1/month)
+- **Mature**: Stable commits (5-20/week), occasional ADRs
+- **Maintenance**: Low commits (<5/week), rare ADRs (<0.5/month)
+
+**Adaptive Threshold Profiles**:
+```typescript
+THRESHOLD_PROFILES = {
+  startup: {
+    staleProposedDays: 14,      // 2 weeks max
+    acceptedUnimplementedDays: 21,
+    outdatedAdrDays: 60,
+    rapidChangeDays: 3
+  },
+  growth: {
+    staleProposedDays: 30,      // 1 sprint cycle
+    acceptedUnimplementedDays: 45,
+    outdatedAdrDays: 90,
+    rapidChangeDays: 7
+  },
+  mature: {
+    staleProposedDays: 90,      // 1 quarter
+    acceptedUnimplementedDays: 90,
+    outdatedAdrDays: 180,
+    rapidChangeDays: 14
+  },
+  maintenance: {
+    staleProposedDays: 180,     // 6 months
+    acceptedUnimplementedDays: 180,
+    outdatedAdrDays: 365,
+    rapidChangeDays: 30
+  }
+}
+```
+
+**ADR Type Modifiers**:
+- Infrastructure ADRs: 1.5x longer timelines (complex deployments)
+- Security ADRs: 0.8x shorter timelines (urgent)
+- Refactoring ADRs: 1.2x longer timelines (low priority)
+- Feature ADRs: 1.0x baseline
+
+### 3. Action Item Analyzer (src/utils/adr-action-analyzer.ts)
+
+**Automated Action Generation**:
+- Analyzes all ADRs with timeline data
+- Generates prioritized action items based on:
+  - ADR status (proposed, accepted, deprecated)
+  - Age and staleness
+  - Implementation status
+  - Project context and thresholds
+
+**Action Urgency Levels**:
+- **Critical** (P0): Blocking issues, security risks
+- **High** (P1): Stale proposed ADRs, long-unimplemented decisions
+- **Medium** (P2): Outdated ADRs needing review
+- **Low** (P3): Minor updates, documentation improvements
+
+**Work Queue Structure**:
+```typescript
+interface AdrWorkQueue {
+  summary: {
+    totalActions: number;
+    criticalCount: number;
+    highCount: number;
+    mediumCount: number;
+    lowCount: number;
+  };
+  actions: ActionItem[];  // Sorted by urgency
+  recommendations: string[];
+}
+```
+
+### 4. Integration
+
+**Enhanced ADR Discovery**:
+- `discoverAdrsInDirectory()` now accepts `includeTimeline` option
+- Timeline data automatically attached to each discovered ADR
+- Optional action generation with `generateActions` flag
+
+**New MCP Tool** (src/index.ts:6800-6950):
+- `analyze_adr_timeline`: Comprehensive timeline analysis with action items
+- Parameters:
+  - `adrDirectory`: Directory to analyze
+  - `generateActions`: Enable action item generation
+  - `thresholdProfile`: Manual profile override
+  - `autoDetectContext`: Auto-select profile (default: true)
+
+### 5. Cache Implementation Decision
+
+**Problem**: The existing `cache.ts` is designed for **prompt-driven AI operations** (returns prompts for AI to execute), but timeline extraction needs **synchronous in-memory caching** for performance.
+
+**Solution**: Implemented a simple in-memory cache directly in `adr-timeline-extractor.ts`:
+- `Map<string, CacheEntry>` for O(1) lookup
+- TTL-based expiration
+- Automatic cleanup on retrieval
+- No external dependencies
+
+**Why Not Use cache.ts**:
+- cache.ts returns `{ prompt, instructions, context }` for AI delegation
+- Timeline extractor needs immediate, synchronous cache access
+- In-memory cache is simpler and more appropriate for this use case
+
+## Consequences
+
+### Positive
+
+1. **Temporal Awareness**: System now understands ADR lifecycles and aging
+2. **Automated Action Planning**: Generates prioritized todo lists automatically
+3. **Context-Aware Analysis**: Thresholds adapt to project phase and velocity
+4. **Smart Performance**: Conditional extraction minimizes expensive operations
+5. **Type Safety**: ADR type modifiers provide realistic timelines
+6. **Better User Experience**: Users get actionable insights, not just data
+
+### Negative
+
+1. **Increased Complexity**: More code to maintain (4 new utility files)
+2. **Git Dependency**: Git extraction requires git to be available
+3. **Cache Divergence**: Two cache systems (prompt-driven and in-memory)
+4. **Context Detection Accuracy**: Auto-detection may misclassify edge-case projects
+
+### Neutral
+
+1. **Breaking Change**: `discoverAdrsInDirectory()` signature changed from 3 params to 2 params + options object
+2. **Memory Usage**: In-memory cache adds modest memory overhead
+3. **Learning Curve**: Users need to understand threshold profiles
+
+## Implementation Notes
+
+### Files Created
+- `src/utils/adr-timeline-extractor.ts` - Multi-source timeline extraction
+- `src/utils/adr-context-detector.ts` - Project context detection
+- `src/utils/adr-action-analyzer.ts` - Action item generation
+- `src/utils/adr-timeline-types.ts` - Shared type definitions
+
+### Files Modified
+- `src/utils/adr-discovery.ts` - Added timeline integration
+- `src/index.ts` - Added `analyze_adr_timeline` MCP tool
+- 20+ files - Updated `discoverAdrsInDirectory()` call sites
+
+### Testing
+- Manual verification: Timeline extraction working correctly
+- Git extraction: Successfully extracts from git history
+- Fallback chain: Content → filesystem fallback working
+- Cache: In-memory cache functioning as expected
+
+## Future Enhancements
+
+1. **Persistent Cache**: Move timeline cache to disk for cross-session persistence
+2. **ML-Based Context Detection**: Use machine learning to improve phase detection
+3. **Custom Thresholds**: Allow users to define custom threshold profiles
+4. **Timeline Visualization**: Generate charts showing ADR lifecycle trends
+5. **Notification Integration**: Alert users when ADRs become stale
+6. **ADR Dependencies**: Track dependencies between ADRs in timeline
+
+## Related ADRs
+
+- ADR-003: Memory-Centric Architecture (cache system design)
+- ADR-001: MCP Protocol Implementation (tool integration)
+
+## References
+
+- Git log extraction: `git log --follow --format="%ai" --diff-filter=A -- <file>`
+- Context detection metrics: Commit frequency, ADR creation rate, team velocity
+- Urgency scoring: Based on ADR status, age, and project context

sample-project/server.js

@@ -0,0 +1,51 @@
+const express = require('express');
+const _jwt = require('jsonwebtoken');
+const { Pool } = require('pg');
+const redis = require('redis');
+
+const app = express();
+const port = process.env.PORT || 3000;
+
+// Database connection
+const pool = new Pool({
+  host: process.env.DB_HOST || 'localhost',
+  database: process.env.DB_NAME || 'mydb',
+  user: process.env.DB_USER || 'postgres',
+  password: process.env.DB_PASSWORD || 'password',
+});
+
+// Redis client
+const _redisClient = redis.createClient({
+  host: process.env.REDIS_HOST || 'localhost',
+  port: process.env.REDIS_PORT || 6379,
+});
+
+// Middleware
+app.use(express.json());
+
+// Routes
+app.get('/api/users', async (req, res) => {
+  try {
+    const result = await pool.query('SELECT * FROM users');
+    res.json(result.rows);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.post('/api/users', async (req, res) => {
+  try {
+    const { name, email } = req.body;
+    const result = await pool.query(
+      'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *',
+      [name, email]
+    );
+    res.status(201).json(result.rows[0]);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.listen(port, () => {
+  console.log(`Server running on port ${port}`);
+});