docs(specs): add AI agent observability & Go collector specs; add reorg & DB docs; update statuses

- Add comprehensive AI Coding Agent Observability spec suite (design, executive summary, quick-reference, performance analysis/summary, implementation checklist, roadmap, etc.)
- Add Go collector artifacts: roadmap, progress summary, collector design/next-steps, integration test results, week1/week2 notes, MVP launch implementation
- Add codebase reorganization materials (quick-wins, phase plans, implementation summaries, terminology rebrand, reorganization plan, UI/UX changes)
- Add database architecture & TimescaleDB implementation files (README, implementation summary, Prisma/migration updates, query optimizations, security summary)
- Create ORGANIZATION.md to document specs conventions and status
- Normalize frontmatter and metadata (timestamps, tags, status, completed dates) across multiple README.md files

All changes are documentation/spec updates to capture design, implementation progress, and next steps for the AI agent observability initiative.

Author: tikazyq

specs/20250721/001-ai-evaluation-system/README.md

@@ -1,12 +1,18 @@
 ---
 status: complete
-created: 2025-07-21
-tags: [evaluation, ai-quality, metrics]
+created: 2025-07-21T00:00:00.000Z
+tags:
+  - evaluation
+  - ai-quality
+  - metrics
 priority: medium
+completed: '2025-11-02'
 ---
 
 # AI Evaluation System
 
+> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-07-21 · **Tags**: evaluation, ai-quality, metrics
+
 **Created**: July 21, 2025  
 **Design Status**: Complete  
 **Related Devlog**: #198

…t-observability/GO_COLLECTOR_PROGRESS.md …gent-observability/collector-progress.mdspecs/20251021/001-ai-agent-observability/GO_COLLECTOR_PROGRESS.md renamed to specs/20251021/001-ai-agent-observability/collector-progress.md specs/20251021/001-ai-agent-observability/GO_COLLECTOR_PROGRESS.md renamed to specs/20251021/001-ai-agent-observability/collector-progress.md

@@ -9,6 +9,7 @@
 ## ✅ What's Completed
 
 ### Phase 0: Project Setup (100% Complete)
+
 - ✅ Go module structure with proper organization
 - ✅ Dependencies: fsnotify, sqlite, logrus, cobra
 - ✅ Makefile with build, test, clean targets
@@ -18,19 +19,22 @@
 ### Phase 1: Core Infrastructure (100% Complete)
 
 **Configuration System**
+
 - ✅ Config loading from `~/.devlog/collector.json`
 - ✅ Environment variable expansion (`${VAR}` syntax)
 - ✅ Validation and defaults
 - ✅ Test coverage: 81.2%
 
 **Log Discovery**
+
 - ✅ OS-specific path detection (darwin/linux/windows)
 - ✅ Support for: Copilot, Claude Code, Cursor, Cline, Aider
 - ✅ Glob pattern matching for version wildcards
 - ✅ Path expansion (home dir, env vars)
 - ✅ Test coverage: 85%+ (from previous milestone)
 
 **File Watching**
+
 - ✅ Real-time monitoring using fsnotify
 - ✅ File change detection (Write/Create events)
 - ✅ Directory watching with recursive support
@@ -40,6 +44,7 @@
 - ✅ Test coverage: 74.7%
 
 **Local Buffer (SQLite)**
+
 - ✅ SQLite-based offline storage
 - ✅ Events table with proper indexing
 - ✅ Store/Retrieve/Delete operations
@@ -51,6 +56,7 @@
 ### Phase 2: Adapter System (50% Complete)
 
 **Base Infrastructure** ✅
+
 - ✅ AgentAdapter interface definition
 - ✅ Registry with adapter registration
 - ✅ Auto-detection via `SupportsFormat()`
@@ -59,6 +65,7 @@
 - ✅ Test coverage: 68.5%
 
 **GitHub Copilot Adapter** ✅
+
 - ✅ JSON log format parsing
 - ✅ Event type mapping (llm_request/llm_response)
 - ✅ Metadata extraction (model, tokens, duration)
@@ -67,13 +74,15 @@
 - ✅ Comprehensive tests
 
 **Pending Adapters** ⏳
+
 - ⏳ Claude Code adapter (Day 10)
 - ⏳ Cursor adapter (bonus)
 - ⏳ Generic fallback adapter (Day 11-12)
 
 ### Phase 3: Backend Communication (100% Complete)
 
 **HTTP Client** ✅
+
 - ✅ RESTful API communication
 - ✅ TLS/HTTPS support
 - ✅ Bearer token authentication
@@ -82,20 +91,23 @@
 - ✅ Test coverage: 75.7%
 
 **Batch Manager** ✅
+
 - ✅ Batching integrated into client
 - ✅ Configurable batch size and interval
 - ✅ Auto-flush on size threshold
 - ✅ Periodic flush timer
 - ✅ Graceful batch handling
 
 **Retry Logic** ✅
+
 - ✅ Exponential backoff (1s, 2s, 4s, 8s...)
 - ✅ Configurable max retries
 - ✅ Network failure handling
 - ✅ Retry logging and monitoring
 - ✅ Context cancellation support
 
 **End-to-End Integration** ✅
+
 - ✅ Complete CLI with start/version/status commands
 - ✅ Graceful shutdown (SIGINT/SIGTERM)
 - ✅ Health check with backend
@@ -107,26 +119,26 @@
 
 ## 📊 Test Coverage Summary
 
-| Package | Coverage | Status |
-|---------|----------|--------|
-| `internal/config` | 81.2% | ✅ Excellent |
-| `internal/watcher` | 74.7% | ✅ Good |
-| `internal/buffer` | 74.8% | ✅ Good |
-| `internal/client` | 75.7% | ✅ Good |
-| `internal/adapters` | 68.5% | ✅ Acceptable |
-| `pkg/types` | N/A | ✅ Type definitions |
-| **Average** | **~75%** | ✅ Good |
+| Package             | Coverage | Status              |
+| ------------------- | -------- | ------------------- |
+| `internal/config`   | 81.2%    | ✅ Excellent        |
+| `internal/watcher`  | 74.7%    | ✅ Good             |
+| `internal/buffer`   | 74.8%    | ✅ Good             |
+| `internal/client`   | 75.7%    | ✅ Good             |
+| `internal/adapters` | 68.5%    | ✅ Acceptable       |
+| `pkg/types`         | N/A      | ✅ Type definitions |
+| **Average**         | **~75%** | ✅ Good             |
 
 ---
 
 ## 🔧 Binary Characteristics
 
-| Metric | Current | Target | Status |
-|--------|---------|--------|--------|
-| Binary Size | ~15MB | < 20MB | ✅ On target |
-| Build Time | ~0.5s | < 2s | ✅ Fast |
-| Startup Time | ~50ms | < 1s | ✅ Excellent |
-| Platforms | darwin/linux/windows | 3 | ✅ Complete |
+| Metric       | Current              | Target | Status       |
+| ------------ | -------------------- | ------ | ------------ |
+| Binary Size  | ~15MB                | < 20MB | ✅ On target |
+| Build Time   | ~0.5s                | < 2s   | ✅ Fast      |
+| Startup Time | ~50ms                | < 1s   | ✅ Excellent |
+| Platforms    | darwin/linux/windows | 3      | ✅ Complete  |
 
 ---
 
@@ -167,6 +179,7 @@ make build
 **Critical Missing Feature**: The collector only captures events from when it starts. Historical logs are ignored.
 
 **Backfill Requirements** (Days 17-20):
+
 - [ ] BackfillManager component
 - [ ] Read log files from arbitrary date range
 - [ ] Timestamp tracking to prevent duplicates
@@ -177,6 +190,7 @@ make build
 - [ ] Resume capability after interruption
 
 **Use Cases**:
+
 - Initial setup with existing context
 - Gap recovery after collector downtime
 - Historical analysis of agent activities
@@ -185,37 +199,43 @@ make build
 ### Phase 2: Additional Adapters (50% Complete)
 
 **Claude Code Adapter** (Day 10):
+
 - [ ] Research Claude Code log format
 - [ ] Implement adapter methods
 - [ ] Map Claude events to standard types
 - [ ] Handle tool_use events
 - [ ] Write tests with samples
 
 **Cursor Adapter** (Bonus):
+
 - [ ] Research Cursor log format
 - [ ] Implement adapter
 - [ ] Write tests
 
 **Generic Adapter** (Days 11-12):
+
 - [ ] Best-effort parsing for unknown formats
 - [ ] Fallback detection
 - [ ] Adapter development guide
 
 ### Phase 5: Distribution (0% Complete)
 
 **NPM Package** (Days 21-22):
+
 - [ ] Create `@codervisor/devlog-collector` npm package
 - [ ] Post-install script for binary selection
 - [ ] Platform detection and binary placement
 - [ ] Test npm install on all platforms
 
 **Auto-start** (Day 23):
+
 - [ ] macOS launchd plist template
 - [ ] Linux systemd service template
 - [ ] Windows service (optional)
 - [ ] Install/uninstall scripts
 
 **Documentation** (Day 24):
+
 - [ ] Comprehensive README
 - [ ] Installation guide
 - [ ] Configuration reference
@@ -227,16 +247,19 @@ make build
 ## 🎯 Next Steps (Priority Order)
 
 ### Immediate (Next 1-2 days)
+
 1. **Implement Claude Code adapter** - Add second major agent support
 2. **Manual integration testing** - Test offline→online transition with real backend
 3. **Performance profiling** - Verify resource usage meets targets
 
 ### Short-term (Next 1 week)
+
 4. **Historical backfill feature** - Critical for real-world usage
 5. **Cursor adapter** - Add third agent support
 6. **Generic adapter** - Fallback for unsupported agents
 
 ### Medium-term (Next 2 weeks)
+
 7. **NPM package** - Easy installation for developers
 8. **Auto-start scripts** - Background daemon setup
 9. **Documentation** - User guides and troubleshooting
@@ -275,13 +298,15 @@ Overall Progress:     █████████████░░░░░░
 ## 💡 Recommendations
 
 ### For Real-World Deployment
+
 1. **Implement backfill first** - Critical for user onboarding
 2. **Add Claude adapter** - Second most popular AI coding assistant
 3. **Test with actual backend** - Verify API contract matches
 4. **Create demo video** - Show collector in action
 5. **Write migration guide** - For users moving from TypeScript collector
 
 ### For Code Quality
+
 1. **Increase test coverage to 80%+** - Currently at ~75%
 2. **Add integration tests** - Test full pipeline with mock backend
 3. **Document internal APIs** - Help future contributors