codex-genesis-harness 0.1.1 → 0.1.5

package/.codebase/QUICK_START_SPEC_IMPACT.md

@@ -0,0 +1,456 @@
+# Quick Start: Using the New Spec Impact System
+
+**Goal**: Understand how to use the new automatic spec propagation features
+
+---
+
+## Scenario 1: API Change During Development
+
+### What Happens
+
+You're in Phase 1 (Auth system). You modify an API endpoint:
+
+```
+Before: GET /api/users/:id → { name, email, role }
+After:  GET /api/users/:id → { id, name, email, roles[] }
+```
+
+### What You Do
+
+```bash
+# 1. Commit your changes
+git add .planning/API_DOCS.md
+git commit -m "feat: add roles array to user API endpoint"
+git push
+
+# OR manually trigger impact analysis
+/spec-change .planning/API_DOCS.md
+```
+
+### What Happens Automatically
+
+```
+GitHub Actions triggers:
+  ✓ Tests run (verify your change works)
+  ✓ spec-impact-engine detects breaking change
+  ✓ Finds Phase 2, 3, 4 depend on this API
+  ✓ Auto-updates Phase 2 SPEC.md (your API call examples)
+  ✓ Auto-updates Phase 2 TEST_CONTRACT.md (5 tests updated)
+  ✓ Auto-updates Phase 3 SPEC.md (2 API calls updated)
+  ✓ Auto-updates Phase 3 TEST_CONTRACT.md (8 tests updated)
+  ✓ Runs tests in Phase 2 and 3 (both pass)
+  ✓ Creates .codebase/IMPACT_REPORT_2026-05-30_14-30.md
+  ✓ Auto-commits: "docs: auto-sync Phase 2,3 specs after API change [CI]"
+  ✓ Auto-updates CURRENT_STATE.md: "Propagated to 2 phases"
+```
+
+### What You See
+
+Email/notification:
+```
+✓ API Change Impact Report
+  Breaking change detected: GET /api/users/:id response format
+
+  Affected phases:
+  - Phase 2: Updated 1 spec, 5 tests ✓
+  - Phase 3: Updated 2 specs, 8 tests ✓
+  - Phase 4: 1 related API call reviewed (manual)
+
+  Timeline impact: +0 hours
+  Status: Ready to proceed
+
+  Developers: Phase 2 and 3 specs already updated!
+```
+
+---
+
+## Scenario 2: Database Schema Change
+
+### What Happens
+
+You're in Phase 2 (Product Catalog). You add a field to products:
+
+```sql
+ALTER TABLE products ADD COLUMN category_id UUID;
+```
+
+### What You Do
+
+```bash
+# Update your implementation files
+git add src/models/Product.ts
+git add .planning/ARCHITECTURE.md
+git commit -m "feat: add product categorization"
+git push
+
+# GitHub Actions triggers automatically
+```
+
+### What Happens Automatically
+
+```
+Spec-impact-engine:
+  ✓ Detects ARCHITECTURE.md changed
+  ✓ Detects database schema modified
+  ✓ Severity: MEDIUM (potential downstream impact)
+  ✓ Finds Phase 3 queries need category_id
+  ✓ Finds Phase 4 admin dashboard needs category column
+  
+  Auto-update Phase 3:
+  ✓ SPEC.md: updated product queries
+  ✓ TEST_CONTRACT.md: added category assertions
+  
+  Flag for review Phase 4:
+  ⚠️ Admin dashboard may need category column
+  ⚠️ Manual review recommended
+  
+  Impact report:
+  - Auto-updated: 1 phase
+  - Manual review needed: 1 phase
+  - Timeline impact: +30 min (Phase 4 review)
+```
+
+### What Phase 3 Developer Sees
+
+```
+Morning update: Phase 3 spec automatically updated!
+
+What changed:
+- Added: Product queries now include category_id
+- Added: 3 new test cases for category filtering
+- Status: Tests already passing ✓
+
+Your action:
+- Read updated SPEC.md (5 min)
+- Confirm changes make sense
+- Continue implementation
+
+Time saved: 1 hour (you would have discovered this later)
+```
+
+---
+
+## Scenario 3: Manually Trigger Impact Analysis
+
+### When to Use
+
+Sometimes you want to manually check impact before committing:
+
+```bash
+# Analyze impact of a spec change WITHOUT committing
+/spec-change .planning/REQUIREMENTS.md
+```
+
+### What You Get
+
+```
+Spec Change Analysis
+
+File: .planning/REQUIREMENTS.md
+Changed section: Shopping Cart Behavior
+
+Old spec: "Cart should persist 1 hour"
+New spec: "Cart should persist 7 days"
+
+Severity: LOW (not breaking, backward compatible)
+
+Affected phases:
+- Phase 3: Cart logic exists
+  Impact: MEDIUM (needs new cleanup job)
+  Action: Update PLAN.md, add background job task
+
+- Phase 4: Payments uses cart
+  Impact: LOW (no change needed)
+  Action: None
+
+- Phase 5: Admin views cart data
+  Impact: LOW (no change needed)
+  Action: None
+
+Recommendation:
+  This change requires Phase 3 update.
+  Timeline impact: +2 hours (add cleanup job)
+  
+  Ready to proceed? Run:
+  /propagate-spec
+```
+
+---
+
+## Scenario 4: Resume Work After Interruption
+
+### You Paused Phase 3 Last Week
+
+```
+Last week: Phase 3 implementation paused mid-way
+
+Questions:
+- Did Phase 1 or 2 specs change while I was gone?
+- Are Phase 3 requirements still current?
+- What should I work on now?
+```
+
+### What You Do
+
+```bash
+/validate-specs
+
+# Checks all phases for alignment
+```
+
+### What You Get
+
+```
+✓ Spec Alignment Check
+
+Phase 1 Status: ✓ Current (last updated 2 days ago)
+Phase 2 Status: ⚠️ Stale (last updated 5 days ago)
+  - API changes: 2 endpoints modified
+  - Phase 2 specs reflect changes ✓
+  
+Phase 3 Status: ❌ MISALIGNED
+  - Depends on Phase 2 API
+  - Phase 3 spec: 5 days old
+  - Phase 2 changed: 2 days ago
+  - SPEC DRIFT DETECTED
+  
+  Missing updates:
+  - Product API response format changed
+  - Phase 3 still expects old format
+  
+  Action needed:
+  Run: /propagate-spec
+  Then run: Phase 3 tests
+  
+  Time: 30 min to sync, 1 hour testing
+
+Phase 4 & 5: ✓ OK (no upstream changes)
+
+Recommendation:
+  1. Run /propagate-spec (auto-sync)
+  2. Run Phase 3 tests
+  3. Continue from RECOVERY_POINTS.md
+```
+
+---
+
+## Scenario 5: Check Project Health
+
+### What You Want to Know
+
+```
+- Are all phases still aligned?
+- Any cascading failures waiting?
+- What's the current project status?
+- Timeline risks?
+```
+
+### What You Do
+
+```bash
+/validate-specs
+```
+
+### What You Get
+
+```
+Comprehensive Spec Validation Report
+
+Project Health: ⚠️ MEDIUM RISK
+  2 phases need attention
+
+Phase 1 (Auth):           ✓ Current
+Phase 2 (Products):       ⚠️ Stale (5 days)
+  - Spec age: 5 days
+  - Last upstream change: 3 days ago
+  - Updates applied: NO
+  - Action: Run /propagate-spec
+
+Phase 3 (Cart):           ⚠️ BLOCKED
+  - Cannot start until Phase 2 aligned
+  - Phase 2 has 2 pending spec changes
+  - Estimated unblock time: 30 min
+
+Phase 4 (Payments):       ✓ Ready (Phase 3 not started yet)
+Phase 5 (Admin):          ✓ Waiting (Phase 4 dependency)
+
+Critical Path: Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5
+
+Timeline Impact:
+  Phase 2 misalignment: +30 min
+  Phase 3 blocked: +1.5 hours
+  
+  Current delay: +2 hours from ideal timeline
+
+Recommendations:
+  1. URGENT: Run /propagate-spec (30 min)
+  2. Validate Phase 3 tests pass (1 hour)
+  3. Unblock Phase 3 work
+  4. Project back on track
+
+Next steps:
+  /propagate-spec
+  Then: Run Phase 2 and 3 tests
+  Then: Resume Phase 3 development
+```
+
+---
+
+## Command Reference
+
+### `/spec-change <file>`
+
+**Purpose**: Detect impact of a single spec change
+
+```bash
+/spec-change .planning/API_DOCS.md
+/spec-change .planning/ARCHITECTURE.md
+/spec-change .planning/REQUIREMENTS.md
+```
+
+**Output**: Impact report with affected phases, severity, recommendations
+
+**Time**: 1-2 minutes
+
+---
+
+### `/propagate-spec`
+
+**Purpose**: Auto-update ALL downstream phases for pending spec changes
+
+```bash
+/propagate-spec
+```
+
+**What it does**:
+1. Scans SPEC_CHANGELOG.md for unpropagated changes
+2. Auto-updates all affected phase specs
+3. Auto-updates all affected test contracts
+4. Runs validation tests
+5. Generates migration guides
+6. Commits changes
+7. Creates comprehensive report
+
+**Output**: Updated phase specs, passed tests, impact report
+
+**Time**: 5-15 minutes depending on number of phases
+
+---
+
+### `/validate-specs`
+
+**Purpose**: Check all phases are aligned with dependencies
+
+```bash
+/validate-specs
+```
+
+**What it checks**:
+1. Each phase spec matches upstream outputs
+2. No stale specs detected
+3. No blocking misalignments
+4. All dependencies satisfied
+5. Timeline cascading calculated
+
+**Output**: Alignment report, recommendations, blockers
+
+**Time**: 2-3 minutes
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+- ✅ Commit your changes immediately after implementation
+- ✅ Let GitHub Actions auto-sync docs
+- ✅ Run `/validate-specs` before starting new phase
+- ✅ Review IMPACT_REPORT.md for breaking changes
+- ✅ Run phase tests after auto-updates
+
+### ❌ DON'T
+
+- ❌ Manually update downstream phase specs (auto-engine does it)
+- ❌ Skip `/validate-specs` before phase start
+- ❌ Commit without running tests first
+- ❌ Ignore impact reports
+- ❌ Work on multiple phases without validation
+
+---
+
+## Troubleshooting
+
+### Specs Not Updating?
+
+```bash
+# Check if changes detected
+git status
+# Should show auto-synced files
+
+# Check impact report
+ls -la .codebase/IMPACT_REPORT*.md
+
+# Manually trigger if needed
+/propagate-spec
+```
+
+### Tests Failing After Auto-Update?
+
+```bash
+# Review what changed
+cat .codebase/IMPACT_REPORT_*.md
+
+# Read updated test contract
+cat .planning/features/NNN/TEST_CONTRACT.md
+
+# Run specific test
+npm test -- Phase3
+
+# If still broken, revert and review manually
+git revert HEAD
+/spec-change .planning/API_DOCS.md
+```
+
+### Need to Understand What Changed?
+
+```bash
+# View detailed impact report
+cat .codebase/IMPACT_REPORT_latest.md
+
+# Check SPEC_CHANGELOG for context
+grep -A 5 "$(date +%Y-%m-%d)" .planning/SPEC_CHANGELOG.md
+
+# Review git diffs
+git diff HEAD~1 .planning/
+```
+
+---
+
+## Time Tracking
+
+**Before Automation**:
+- Detect change: 5 min
+- Manual update Phase 2: 1 hour
+- Manual update Phase 3: 1.5 hours
+- Manual update Phase 4: 45 min
+- Test all phases: 1 hour
+- **Total**: ~4.5 hours
+
+**After Automation**:
+- Commit change: 2 min
+- Auto-detect + update: 2 min
+- Tests run: 5 min
+- Review impact report: 5 min
+- **Total**: ~15 minutes
+
+**Time Saved**: ~4 hours per spec change ✅
+
+---
+
+## Next: Full Harness Documentation
+
+See:
+- `.codex/skills/spec-impact-engine/SKILL.md` - Full technical details
+- `.codebase/PHASE_DEPENDENCY_MAP.md` - Phase structure
+- `.codebase/IMPLEMENTATION_COMPLETE.md` - What was built
+- `.codex/skills/genesis-harness/SKILL.md` - Full Genesis Harness reference

package/.codebase/README.md

@@ -0,0 +1,139 @@
+# Repository Memory System
+
+The `.codebase/` directory contains persistent, compressed documentation about the project state, architecture, and ongoing work. This is the **single source of truth** for understanding the codebase.
+
+## Core Reference Files
+
+### CURRENT_STATE.md
+**What**: Snapshot of the project's current status
+**Update**: After every significant change or phase completion
+**When to read**: Before starting work to understand what's been done
+
+### MODULE_INDEX.md
+**What**: Complete inventory of all modules, skills, and components
+**Update**: When adding/removing modules or significant restructures
+**When to read**: To find where functionality lives
+
+### TEST_MATRIX.md
+**What**: Coverage status of all testable components
+**Update**: After writing tests, every sprint
+**When to read**: To identify testing gaps and priorities
+
+### ARCHITECTURE.md
+**What**: System design, data flow, and integration points
+**Update**: When architecture decisions change
+**When to read**: Before major refactoring or new features
+
+### API_CONTRACTS.md
+**What**: All API endpoints, schemas, and breaking changes
+**Update**: When API changes (must update before implementation)
+**When to read**: Before working on API features
+
+### DOMAIN_MODELS.md
+**What**: Core data structures and business logic rules
+**Update**: When domain models evolve
+**When to read**: To understand business constraints
+
+### PIPELINE_FLOW.md
+**What**: AI pipeline orchestration and data flow
+**Update**: When pipeline configuration changes
+**When to read**: To understand job execution order and dependencies
+
+### DEPENDENCY_GRAPH.md
+**What**: Module dependencies and relationships
+**Update**: When adding new dependencies or removing unused ones
+**When to read**: Before major refactoring to understand impact
+
+### UI_ROUTES.md
+**What**: Frontend routes, pages, and navigation flow
+**Update**: When adding/removing pages or changing routes
+**When to read**: To understand frontend structure
+
+### EVOLUTION_PLAN.md
+**What**: Future features, roadmap, and planned changes
+**Update**: During planning phases
+**When to read**: To align current work with long-term goals
+
+### KNOWN_PROBLEMS.md
+**What**: Active bugs, technical debt, and limitations
+**Update**: When discovering or fixing issues
+**When to read**: Before starting features (may need workarounds)
+
+## Context Summaries
+
+The `context/` subdirectory contains compressed summaries for quick reference:
+
+- `backend-summary.md` - Backend services, APIs, databases
+- `frontend-summary.md` - UI structure, routes, components
+- `pipeline-summary.md` - Job orchestration and data flow
+- `providers-summary.md` - External services and integrations
+- `render-summary.md` - Rendering engines and output formats
+- `tests-summary.md` - Test coverage and strategies
+
+**These are read-only reference documents.** Update the source files, not these summaries.
+
+## Maintenance Guidelines
+
+### Before Starting Any Task
+
+1. Read `CURRENT_STATE.md` - Understand what's been done
+2. Read relevant reference files based on your work type
+3. Check `KNOWN_PROBLEMS.md` - Avoid duplicating known issues
+
+### After Completing Work
+
+1. Update `CURRENT_STATE.md` with your changes
+2. Update any reference files affected by your work
+3. If you solved a known problem, remove from `KNOWN_PROBLEMS.md`
+4. Create a decision log in `../observability/decision-logs/`
+
+### Keeping Memory Fresh
+
+- Do NOT let `.codebase/` files go stale
+- If a file is >6 months old without updates, it's likely outdated
+- Run `./scripts/verify.sh` to check consistency
+- When in doubt, inspect actual code rather than trusting old docs
+
+## File Size Expectations
+
+- Each file should be **2000-5000 lines MAX**
+- If a file grows larger, split into subtopics
+- Use `context/` subdirectory for compressed summaries
+- Link to specific sections, don't duplicate content
+
+## Structure
+
+```
+.codebase/
+├── README.md (this file)
+├── CURRENT_STATE.md
+├── MODULE_INDEX.md
+├── TEST_MATRIX.md
+├── ARCHITECTURE.md
+├── API_CONTRACTS.md
+├── DOMAIN_MODELS.md
+├── PIPELINE_FLOW.md
+├── DEPENDENCY_GRAPH.md
+├── UI_ROUTES.md
+├── EVOLUTION_PLAN.md
+├── KNOWN_PROBLEMS.md
+└── context/
+    ├── backend-summary.md
+    ├── frontend-summary.md
+    ├── pipeline-summary.md
+    ├── providers-summary.md
+    ├── render-summary.md
+    └── tests-summary.md
+```
+
+## Quick Reference
+
+| Task | Read First | Update After |
+|------|-----------|--------------|
+| New feature | CURRENT_STATE, EVOLUTION_PLAN | CURRENT_STATE, TEST_MATRIX |
+| Bug fix | KNOWN_PROBLEMS, CURRENT_STATE | KNOWN_PROBLEMS, CURRENT_STATE |
+| Refactoring | ARCHITECTURE, DEPENDENCY_GRAPH | ARCHITECTURE, DEPENDENCY_GRAPH |
+| Testing | TEST_MATRIX | TEST_MATRIX, CURRENT_STATE |
+| API work | API_CONTRACTS | API_CONTRACTS, CURRENT_STATE |
+| Performance | PIPELINE_FLOW, DOMAIN_MODELS | CURRENT_STATE |
+| Deployment | CURRENT_STATE, EVOLUTION_PLAN | CURRENT_STATE |