codex-genesis-harness 0.1.0 → 0.1.4

package/.codex/skills/genesis-docs-automation/examples/example.md

@@ -0,0 +1,59 @@
+# Example: Auto-Sync Docs After Adding a New API Endpoint
+
+## Scenario
+
+A developer adds a new `POST /api/v1/notifications` endpoint in Phase 3 (backend implementation). After tests pass, genesis-docs-automation automatically detects the change and updates all related documentation.
+
+## Trigger
+
+```
+/update-docs
+```
+
+Or auto-triggered when `POST /api/v1/notifications` handler passes integration tests.
+
+## Detected Changes
+
+```
+Changed files:
+  - src/api/handlers/notificationHandler.ts  (Phase 3: backend)
+  - contracts/api/Notification/request.json   (Phase 1: contract)
+  - tests/integration/notifications.test.ts  (Phase 2: tests)
+
+Doc updates needed:
+  - API Reference → Add POST /api/v1/notifications endpoint
+  - Architecture Docs → Note notification system added
+  - SPEC_CHANGELOG.md → FEATURE entry
+  - IMPLEMENTATION_HANDOFF.md → Updated for Phase 4
+```
+
+## Auto-Generated Output
+
+**`.docs/API_REFERENCE.md`** updated with:
+```markdown
+### POST /api/v1/notifications
+
+**Description**: Send a notification to a user
+
+**Parameters**:
+- `userId` (string, required): Target user ID
+- `message` (string, required): Notification message text
+- `type` (string, optional): Notification type (default: "info")
+
+**Response** (201):
+{ "id": "uuid", "status": "queued", "createdAt": "..." }
+```
+
+**`SPEC_CHANGELOG.md`** auto-appended:
+```
+[2026-05-31] FEATURE: Added POST /api/v1/notifications endpoint
+  - Sends user notifications with optional type classification
+  - Tests: tests/integration/notifications.test.ts (8 tests)
+```
+
+## Outcome
+
+- ✅ API docs synced in 5 minutes (vs 30 min manual)
+- ✅ Changelog entry accurate
+- ✅ Cross-phase references validated
+- ✅ No TODO markers remaining

package/.codex/skills/genesis-docs-automation/observability/docs-tracking.md

@@ -0,0 +1,382 @@
+# Docs Tracking & Observability
+
+**Purpose**: Track all documentation updates, metrics, and enable continuous improvement
+
+**Location**: `.codebase/observability/docs-tracking.md`
+
+---
+
+## 📋 DOCS_UPDATE_LOG.md Format
+
+Create entries in `.codebase/DOCS_UPDATE_LOG.md`:
+
+```markdown
+# Documentation Update Log
+
+## Entry #[N] | [YYYY-MM-DD HH:MM UTC]
+
+### Change Summary
+- **Type**: Feature / Bug Fix / Deprecated / Breaking / Internal
+- **Severity**: Critical / High / Medium / Low
+- **Status**: ✅ Complete / ⏳ In Progress / ❌ Failed
+
+### Changes Detected
+- Phase [X] File 1: [Change type]
+- Phase [X] File 2: [Change type]
+
+### Docs Updated
+- ✅ [docs/file1.md](path) - [What changed]
+- ✅ [docs/file2.md](path) - [What changed]
+- ⏳ [docs/file3.md](path) - [Blocked, reason]
+
+### Validation Results
+- Syntax: ✅ Valid
+- References: ✅ All valid
+- Phase Alignment: ✅ Aligned
+- Completeness: 100% (N/N items documented)
+
+### Manual Review Gate
+- Breaking Change: ❌ NO
+- Security Issue: ❌ NO
+- Incomplete Docs: ❌ NO
+
+**Overall Status**: ✅ READY FOR COMMIT
+
+### Metrics
+- Changes detected: [N]
+- Docs files updated: [N]
+- Time taken: [X minutes]
+- Manual review required: YES / NO
+
+### Notes
+- [Any additional notes or context]
+- Handled edge case: [If any]
+- Issues encountered: [If any]
+
+---
+```
+
+---
+
+## 📊 Metrics CSV Format
+
+Create `.codebase/docs-metrics.csv`:
+
+```csv
+date,timestamp,change_type,severity,files_changed,docs_files_updated,time_minutes,phases_affected,test_pass_rate,manual_review_required,status,issues_found,committed
+2026-05-31T10:35:00Z,May 31 2026,FEATURE,MEDIUM,5,3,35,5,100%,NO,READY,0,YES
+2026-05-30T14:20:00Z,May 30 2026,BUG_FIX,HIGH,2,2,22,2,100%,NO,READY,1,YES
+2026-05-29T09:15:00Z,May 29 2026,BREAKING,CRITICAL,3,4,45,3,100%,YES,MANUAL_REVIEW,2,NO
+```
+
+---
+
+## 📈 Aggregated Metrics Report
+
+**Template for monthly reports** (save as `docs-metrics-[YYYY-MM].md`):
+
+```markdown
+# Documentation Metrics Report
+
+**Period**: [Month] [Year]
+**Generated**: [Date]
+
+---
+
+## Executive Summary
+
+| Metric | Value | Change | Target |
+|--------|-------|--------|--------|
+| **Avg Docs Update Time** | 28 min | ↓ 5% | < 30 min |
+| **Docs Completeness** | 98% | ↑ 2% | 95%+ |
+| **Cross-Phase Alignment** | 100% | ↑ 0% | 100% |
+| **Unresolved Issues** | 2 | ↑ 1 | 0 |
+| **Automation Success Rate** | 95% | ↓ 2% | 99%+ |
+
+---
+
+## Changes by Type
+
+### Feature Changes: 12
+- New endpoints: 5
+- New fields: 4
+- New methods: 3
+- Avg time: 32 minutes
+- Manual reviews: 0
+
+### Bug Fixes: 8
+- High severity: 2
+- Medium severity: 4
+- Low severity: 2
+- Avg time: 18 minutes
+- Manual reviews: 1 (security-related)
+
+### Breaking Changes: 2
+- Endpoint removals: 1
+- Field removals: 1
+- Avg time: 52 minutes
+- Manual reviews: 2 (both required)
+
+### Documentation Only: 4
+- Avg time: 12 minutes
+- Manual reviews: 0
+
+---
+
+## Docs Completeness by Category
+
+| Category | Complete | Missing | % |
+|----------|----------|---------|---|
+| API Reference | 24/24 | 0 | 100% |
+| Implementation Guides | 8/8 | 0 | 100% |
+| Architecture Docs | 6/6 | 0 | 100% |
+| Changelog Entries | 26/26 | 0 | 100% |
+| Migration Guides | 4/4 | 0 | 100% |
+| **Total** | **68/68** | **0** | **100%** |
+
+---
+
+## Phase Alignment Audit
+
+| Alignment Check | Result | Notes |
+|-----------------|--------|-------|
+| Phase 1 ↔ Phase 3 | ✅ 100% | Contract ⊂ Implementation |
+| Phase 3 ↔ Phase 4 | ✅ 100% | Backend ⊂ SDK |
+| Phase 4 ↔ Phase 5 | ✅ 100% | SDK ⊂ Tests |
+| Error Code Alignment | ✅ 100% | All phases agree |
+| Type Definition Alignment | ✅ 100% | No mismatches |
+
+---
+
+## Issues & Resolutions
+
+### Issue #1: Avatar URL Field Misalignment
+- **Found**: May 28
+- **Phase**: Phase 4 ↔ Phase 5
+- **Cause**: SDK didn't include new optional field
+- **Resolution**: Updated Phase 4 type definition to include avatarUrl
+- **Status**: ✅ Resolved
+- **Time to Resolve**: 15 minutes
+
+### Issue #2: Deprecated Endpoint Not Documented
+- **Found**: May 29
+- **Phase**: Phase 1 ↔ Documentation
+- **Cause**: Migration guide not created during deprecation
+- **Resolution**: Created migration guide linking /api/auth/register → /api/users/register
+- **Status**: ✅ Resolved
+- **Time to Resolve**: 22 minutes
+
+---
+
+## Automation Performance
+
+### Auto-Update Success Rate
+
+- **Total Updates**: 26
+- **Successful**: 25 (96%)
+- **Failed**: 1 (4%)
+  - Reason: Circular reference detection (false positive)
+  - Action: Filed bug, workaround created
+
+### Time Saved vs Manual
+
+| Phase | Manual Time | Automated Time | Savings | # Updates |
+|-------|------------|---|---------|-----------|
+| Detection | 15 min | 3 min | 80% | 26 |
+| Analysis | 20 min | 8 min | 60% | 26 |
+| Update | 30 min | 15 min | 50% | 26 |
+| Validation | 10 min | 2 min | 80% | 26 |
+| **Total** | **75 min** | **28 min** | **63%** | **26** |
+
+**Average per change**: 75 min → 28 min (63% reduction)
+**Monthly savings**: ~18 hours
+**Projected annual**: ~216 hours
+
+---
+
+## Recommendations
+
+### 1. Improve Avatar Field Handling
+- **Action**: Add avatar field to default user type template
+- **Priority**: Medium
+- **Impact**: Prevent similar issues in future
+- **Timeline**: Next sprint
+
+### 2. Enhance Circular Reference Detection
+- **Action**: Improve algorithm to reduce false positives
+- **Priority**: Low
+- **Impact**: Reduce manual review gate triggers
+- **Timeline**: When next PR review happens
+
+### 3. Add Performance Tracking
+- **Action**: Track response time metrics for documented endpoints
+- **Priority**: Medium
+- **Impact**: Enable performance regression detection
+- **Timeline**: Next quarter
+
+---
+
+## Trend Analysis
+
+### Docs Update Time Trend
+
+```
+Week 1: Avg 35 min
+Week 2: Avg 32 min ↓ 9%
+Week 3: Avg 28 min ↓ 13%
+Week 4: Avg 26 min ↓ 26%
+
+Trend: ↓ Improving (learning curve flattening)
+Forecast: Will stabilize around 25 min/update
+```
+
+### Completeness Trend
+
+```
+Week 1: 85%
+Week 2: 90% ↑ 6%
+Week 3: 96% ↑ 7%
+Week 4: 98% ↑ 2%
+
+Trend: ↑ Improving
+Target: 99%+ achievable in Week 5
+```
+
+### Manual Review Rate
+
+```
+Week 1: 20% of updates required manual review
+Week 2: 15% ↓ 25%
+Week 3: 12% ↓ 20%
+Week 4: 8% ↓ 33%
+
+Trend: ↓ Improving (fewer edge cases)
+Target: < 5% (only breaking changes)
+```
+
+---
+
+## Template Query Examples
+
+### Query 1: Find Breaking Changes in May
+
+```sql
+SELECT * FROM docs_updates
+WHERE date >= '2026-05-01' 
+  AND date < '2026-06-01'
+  AND change_type = 'BREAKING'
+ORDER BY date DESC;
+```
+
+**Result**:
+- Entry #67: Removed legacyId field (May 29)
+- Entry #72: Deprecated old endpoint (May 31)
+
+### Query 2: Calculate Average Update Time by Type
+
+```sql
+SELECT 
+  change_type,
+  AVG(time_minutes) as avg_time,
+  COUNT(*) as count
+FROM docs_updates
+WHERE date >= '2026-05-01'
+GROUP BY change_type
+ORDER BY avg_time DESC;
+```
+
+**Result**:
+| change_type | avg_time | count |
+|-------------|----------|-------|
+| BREAKING | 52 | 2 |
+| FEATURE | 32 | 12 |
+| BUG_FIX | 18 | 8 |
+| INTERNAL | 12 | 4 |
+
+### Query 3: Manual Review Triggers
+
+```sql
+SELECT 
+  date,
+  change_type,
+  severity,
+  reason_for_manual_review
+FROM docs_updates
+WHERE manual_review_required = 'YES'
+  AND date >= '2026-05-01'
+ORDER BY date DESC;
+```
+
+**Result**:
+| date | change_type | reason |
+|------|------------|--------|
+| 2026-05-29 | BREAKING | Field removal |
+| 2026-05-25 | FEATURE | New service |
+| 2026-05-20 | BREAKING | Endpoint removal |
+
+### Query 4: Issues by Category
+
+```sql
+SELECT 
+  category,
+  COUNT(*) as issue_count,
+  AVG(time_to_resolve_minutes) as avg_resolve_time
+FROM docs_issues
+WHERE status = 'RESOLVED'
+GROUP BY category;
+```
+
+**Result**:
+| category | issue_count | avg_resolve_time |
+|----------|------------|-----------------|
+| Misalignment | 3 | 18 min |
+| Missing docs | 2 | 22 min |
+| Performance | 1 | 15 min |
+
+---
+
+## Archive Strategy
+
+**Keep recent**: Monthly reports for last 6 months (active)
+**Archive**: Reports older than 6 months to `.codebase/archive/docs-metrics-2026-Q1.md`
+**Compress**: Quarterly summaries in `.codebase/docs-metrics-yearly.md`
+
+---
+
+## Continuous Improvement Actions
+
+### Completed (This Month)
+
+- [x] Implemented auto-update for changelog entries
+- [x] Added cross-phase alignment validation
+- [x] Reduced average update time from 75 min to 28 min
+
+### In Progress
+
+- [ ] Improve circular reference detection (reduce false positives)
+- [ ] Add performance metric tracking for endpoints
+
+### Planned (Next Month)
+
+- [ ] Add coverage metrics to docs validation
+- [ ] Create quarterly docs health report
+- [ ] Implement docs version tracking (diff on changes)
+
+---
+
+## Monthly Sign-Off
+
+**Documentation Health**: ✅ EXCELLENT
+- Completeness: 98% (target: 95%+) ✅
+- Phase Alignment: 100% (target: 100%) ✅
+- Update Speed: 28 min avg (target: < 30 min) ✅
+- Manual Review Rate: 8% (target: < 10%) ✅
+
+**Recommendation**: Continue current approach, implement improvements from "Planned" section
+
+**Approver**: _________________________
+**Date**: _________________________
+
+---
+
+**Last Updated**: [Date] | **Next Review**: [Date] | **Status**: ACTIVE