codex-genesis-harness 0.1.1 → 0.1.4

package/.codex/skills/spec-impact-engine/detect-spec-changes.sh

@@ -0,0 +1,262 @@
+#!/bin/bash
+# Spec Impact Engine - Core Detection Script
+# Detects spec changes and calculates downstream impact
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../../" && pwd)"
+PLANNING_DIR="$REPO_ROOT/.planning"
+CODEBASE_DIR="$REPO_ROOT/.codebase"
+TIMESTAMP=$(date +%Y-%m-%d_%H-%M-%S)
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Log functions
+log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
+log_success() { echo -e "${GREEN}[✓]${NC} $1"; }
+log_warning() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[✗]${NC} $1"; }
+
+# Check if running in git repo
+check_git_repo() {
+  if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    log_error "Not a git repository"
+    return 1
+  fi
+  return 0
+}
+
+# Get changed files since last commit
+get_changed_files() {
+  local changed_docs=""
+  
+  # Check REQUIREMENTS.md
+  if git diff --name-only | grep -q "\.planning/REQUIREMENTS\.md"; then
+    changed_docs="$changed_docs REQUIREMENTS.md"
+  fi
+  
+  # Check API_DOCS.md
+  if git diff --name-only | grep -q "\.planning/API_DOCS\.md"; then
+    changed_docs="$changed_docs API_DOCS.md"
+  fi
+  
+  # Check ARCHITECTURE.md
+  if git diff --name-only | grep -q "\.planning/ARCHITECTURE\.md"; then
+    changed_docs="$changed_docs ARCHITECTURE.md"
+  fi
+  
+  # Check DESIGN.md
+  if git diff --name-only | grep -q "\.planning/DESIGN\.md"; then
+    changed_docs="$changed_docs DESIGN.md"
+  fi
+  
+  # Check STACK.md
+  if git diff --name-only | grep -q "\.planning/STACK\.md"; then
+    changed_docs="$changed_docs STACK.md"
+  fi
+  
+  # Check feature specs
+  if git diff --name-only | grep -q "\.planning/features/.*/SPEC\.md"; then
+    changed_docs="$changed_docs FEATURE_SPECS"
+  fi
+  
+  # Check bug plans
+  if git diff --name-only | grep -q "\.planning/bugs/.*/PLAN\.md"; then
+    changed_docs="$changed_docs BUG_PLANS"
+  fi
+  
+  echo "$changed_docs"
+}
+
+# Detect breaking changes
+detect_breaking_changes() {
+  local file="$1"
+  local breaking_changes=""
+  
+  log_info "Analyzing $file for breaking changes..."
+  
+  # API breaking changes patterns
+  if [[ "$file" == "API_DOCS.md" ]]; then
+    # Check for endpoint signature changes
+    if git diff "$PLANNING_DIR/API_DOCS.md" | grep -E "^\-.*GET|POST|PUT|DELETE" > /dev/null; then
+      breaking_changes="endpoint_signature_changed"
+      log_warning "BREAKING: Endpoint signature changed"
+    fi
+    
+    # Check for response format changes
+    if git diff "$PLANNING_DIR/API_DOCS.md" | grep -E "^\-.*\{.*\}" > /dev/null; then
+      breaking_changes="$breaking_changes response_format_changed"
+      log_warning "BREAKING: Response format changed"
+    fi
+  fi
+  
+  # Database breaking changes
+  if [[ "$file" == "ARCHITECTURE.md" ]] || [[ "$file" == "REQUIREMENTS.md" ]]; then
+    if git diff "$PLANNING_DIR/$file" | grep -E "^\-.*schema|database|model" > /dev/null; then
+      breaking_changes="$breaking_changes schema_changed"
+      log_warning "BREAKING: Database schema changed"
+    fi
+  fi
+  
+  echo "$breaking_changes"
+}
+
+# Identify affected phases
+identify_affected_phases() {
+  local change_type="$1"
+  local affected_phases=""
+  
+  if [[ -f "$CODEBASE_DIR/PHASE_DEPENDENCY_MAP.md" ]]; then
+    log_info "Reading phase dependency map..."
+    # This would parse PHASE_DEPENDENCY_MAP.md to find affected phases
+    # For now, scan all phase folders
+    
+    for phase_dir in "$PLANNING_DIR"/features/*/; do
+      if [[ -f "$phase_dir/SPEC.md" ]]; then
+        local phase_name=$(basename "$phase_dir")
+        affected_phases="$affected_phases $phase_name"
+      fi
+    done
+    
+    log_success "Identified $(echo $affected_phases | wc -w) affected phases"
+  fi
+  
+  echo "$affected_phases"
+}
+
+# Calculate impact severity
+calculate_severity() {
+  local change_type="$1"
+  local severity="low"
+  
+  case "$change_type" in
+    *endpoint_signature_changed*)
+      severity="high"
+      ;;
+    *response_format_changed*)
+      severity="high"
+      ;;
+    *schema_changed*)
+      severity="medium"
+      ;;
+    *requirement_changed*)
+      severity="medium"
+      ;;
+    *)
+      severity="low"
+      ;;
+  esac
+  
+  echo "$severity"
+}
+
+# Generate impact report
+generate_impact_report() {
+  local changed_file="$1"
+  local breaking_changes="$2"
+  local affected_phases="$3"
+  local severity="$4"
+  
+  local report_file="$CODEBASE_DIR/IMPACT_REPORT_$TIMESTAMP.md"
+  
+  log_info "Generating impact report: $report_file"
+  
+  cat > "$report_file" << EOF
+# Spec Change Impact Report
+
+**Date**: $(date '+%Y-%m-%d %H:%M:%S')
+**Changed File**: $changed_file
+**Breaking Changes**: $breaking_changes
+**Severity**: $severity
+
+## Summary
+
+File \`$changed_file\` was modified.
+
+**Change Type(s)**: $breaking_changes
+**Severity Level**: $severity
+
+## Affected Phases
+
+EOF
+
+  local phase_count=0
+  for phase in $affected_phases; do
+    phase_count=$((phase_count + 1))
+    echo "- $phase" >> "$report_file"
+  done
+  
+  cat >> "$report_file" << EOF
+
+**Total Phases Affected**: $phase_count
+
+## Recommended Actions
+
+1. ✅ Review breaking changes
+2. → Update affected phase specs
+3. → Update test contracts
+4. → Run validation tests
+5. → Generate migration guides
+6. → Update ROADMAP.md if timeline affected
+
+## Validation Checklist
+
+- [ ] All affected phases reviewed
+- [ ] Phase specs updated
+- [ ] Tests passing
+- [ ] Migration guides created
+- [ ] Timeline recalculated
+- [ ] Team notified
+
+## Next Steps
+
+Run: \`invoke spec-impact-engine /propagate-spec\`
+
+To automatically update all affected downstream phases.
+
+EOF
+
+  log_success "Impact report created: $report_file"
+  cat "$report_file"
+}
+
+# Main execution
+main() {
+  log_info "Starting spec impact analysis..."
+  
+  if ! check_git_repo; then
+    log_error "Must be run from a git repository"
+    exit 1
+  fi
+  
+  local changed_files=$(get_changed_files)
+  
+  if [[ -z "$changed_files" ]]; then
+    log_warning "No spec files changed"
+    exit 0
+  fi
+  
+  log_success "Detected changes: $changed_files"
+  
+  for file in $changed_files; do
+    log_info "Processing: $file"
+    
+    local breaking=$(detect_breaking_changes "$file")
+    if [[ -n "$breaking" ]]; then
+      local affected=$(identify_affected_phases "$breaking")
+      local severity=$(calculate_severity "$breaking")
+      
+      generate_impact_report "$file" "$breaking" "$affected" "$severity"
+    fi
+  done
+  
+  log_success "Spec impact analysis complete"
+}
+
+main "$@"

package/.codex/skills/spec-impact-engine/examples/example.md

@@ -0,0 +1,98 @@
+# Example: Detecting Impact of a Breaking API Change
+
+## Scenario
+
+Phase 1 API contract changes — `GET /api/users/:id` response field `role` (string) is replaced by `roles` (array of strings). This is a breaking change.
+
+## Trigger
+
+```bash
+/spec-change .planning/API_DOCS.md
+# spec-impact-engine activates automatically
+```
+
+Or manually:
+
+```bash
+invoke spec-impact-engine
+# Parameters:
+# changed_files: [".planning/API_DOCS.md"]
+# impact_scope: "all"
+# auto_update: true
+# notify: true
+```
+
+## Phase 1: Change Detection
+
+```
+Analyzing: .planning/API_DOCS.md
+
+Detected change:
+  Type: BREAKING
+  Section: GET /api/users/:id → response
+  Old: { name, email, role: string }
+  New: { id, name, email, roles: string[] }
+  Severity: HIGH
+  Reason: Field renamed and type changed (string → array)
+```
+
+## Phase 2: Dependency Analysis
+
+```
+Building dependency graph from .codebase/PHASE_DEPENDENCY_MAP.md...
+
+Phase 2 (Tests):   depends on Phase 1 API ← AFFECTED
+Phase 3 (Backend): depends on Phase 1 API ← AFFECTED
+Phase 4 (SDK):     depends on Phase 3     ← AFFECTED (transitive)
+Phase 5 (E2E):     depends on Phase 4     ← AFFECTED (transitive)
+```
+
+## Phase 3: Impact Calculation
+
+```
+Impact chain (DFS from Phase 1):
+
+  Phase 2 → MEDIUM: 5 mock assertions use `role` field
+  Phase 3 → HIGH:   Response builder returns `role`, not `roles[]`
+  Phase 4 → MEDIUM: interface User has `role: string`, not `roles: string[]`
+  Phase 5 → LOW:    2 E2E scenarios check for role-based access
+
+Update order: Phase 2 → Phase 3 → Phase 4 → Phase 5
+Total estimate: ~2 hours
+```
+
+## Phase 4: Auto-Updates Applied
+
+- **Phase 2** `tests/api-mocks.test.ts`:
+  - `expect(response.role).toBe('admin')` → `expect(response.roles).toContain('admin')`
+- **Phase 3** `contracts/api/GetUser/response.json`:
+  - Schema updated: `roles: { type: "array", items: { type: "string" } }`
+- **Phase 4** `types/api.ts`:
+  - `role: string` → `roles: string[]`
+- **Phase 5** `playwright/e2e/user-profile.spec.ts`:
+  - Updated 2 role-check assertions
+
+## Impact Report Generated
+
+```
+.codebase/IMPACT_REPORT_2026-05-31_14-30-00.md created:
+  - 4 phases affected
+  - 8 files auto-updated
+  - 2 hours timeline impact
+  - Migration guide generated: templates/migration-guide.md
+```
+
+## SPEC_CHANGELOG.md Entry
+
+```
+- 2026-05-31T14:30:00Z | BREAKING | API field role → roles[] in GET /api/users/:id
+  Affected: Phase 2, 3, 4, 5 | Auto-updated: yes | Migration guide: IMPACT_REPORT_...
+```
+
+## Outcome
+
+- ✅ Breaking change detected immediately
+- ✅ All 4 downstream phases auto-updated
+- ✅ Tests re-run and passing
+- ✅ Migration guide generated
+- ✅ 45 min manual discovery + update → 30 min automated

package/.codex/skills/spec-impact-engine/templates/impact-report.md

@@ -0,0 +1,248 @@
+# Spec Change Impact Report
+
+**Report ID**: IMPACT_{{TIMESTAMP}}  
+**Generated**: {{DATE}}  
+**Change Source**: {{CHANGED_FILE}}  
+**Severity**: {{SEVERITY}} <!-- HIGH | MEDIUM | LOW -->  
+**Change Type**: {{CHANGE_TYPE}} <!-- BREAKING | FEATURE | INTERNAL | DOC -->  
+**Reporter**: spec-impact-engine v1.0  
+
+---
+
+## Executive Summary
+
+{{CHANGE_SUMMARY_ONE_LINER}}
+
+| Field | Value |
+|-------|-------|
+| Changed File | `{{CHANGED_FILE}}` |
+| Changed Section | `{{CHANGED_SECTION}}` |
+| Change Type | {{CHANGE_TYPE}} |
+| Severity | {{SEVERITY}} |
+| Phases Affected | {{AFFECTED_PHASE_COUNT}} |
+| Estimated Update Time | {{ESTIMATED_HOURS}} hours |
+| Manual Review Required | {{MANUAL_REVIEW}} |
+
+---
+
+## Change Details
+
+### What Changed
+
+**Before**:
+```
+{{OLD_VALUE}}
+```
+
+**After**:
+```
+{{NEW_VALUE}}
+```
+
+### Why It Changed
+
+{{CHANGE_REASON}}
+
+### Breaking Status
+
+- [ ] **BREAKING** — Existing consumers will break without migration
+- [ ] **FEATURE** — New capability added (backward compatible)
+- [ ] **INTERNAL** — No external impact
+
+**Breaking assessment**: {{BREAKING_ASSESSMENT}}
+
+---
+
+## Affected Phases
+
+| Phase | Dependency Type | Impact Level | Action Required | Status |
+|-------|----------------|-------------|----------------|--------|
+| Phase 1 (Contracts) | {{P1_DEP_TYPE}} | {{P1_IMPACT}} | {{P1_ACTION}} | {{P1_STATUS}} |
+| Phase 2 (Tests) | {{P2_DEP_TYPE}} | {{P2_IMPACT}} | {{P2_ACTION}} | {{P2_STATUS}} |
+| Phase 3 (Backend) | {{P3_DEP_TYPE}} | {{P3_IMPACT}} | {{P3_ACTION}} | {{P3_STATUS}} |
+| Phase 4 (SDK) | {{P4_DEP_TYPE}} | {{P4_IMPACT}} | {{P4_ACTION}} | {{P4_STATUS}} |
+| Phase 5 (E2E) | {{P5_DEP_TYPE}} | {{P5_IMPACT}} | {{P5_ACTION}} | {{P5_STATUS}} |
+
+**Legend**:
+- Impact: HIGH = code must change, MEDIUM = review needed, LOW = informational, N/A = not affected
+- Status: ⚠️ NEEDS UPDATE | 🔍 REVIEW | ✅ OK | ⛔ BLOCKED
+
+---
+
+## Detailed Impact Per Phase
+
+### Phase 2: Tests
+
+**Files affected**:
+- `{{P2_FILE_1}}` — {{P2_CHANGE_DESC_1}}
+- `{{P2_FILE_2}}` — {{P2_CHANGE_DESC_2}}
+
+**Actions**:
+- [ ] Update mock data: replace `{{OLD_FIELD}}` with `{{NEW_FIELD}}`
+- [ ] Update assertions: verify response includes `{{NEW_FIELD}}`
+- [ ] Remove obsolete assertions for `{{REMOVED_FIELD}}`
+- [ ] Add test cases for new `{{NEW_BEHAVIOR}}`
+- [ ] Validate: run `npm test -- {{P2_TEST_PATTERN}}`
+
+**Estimated time**: {{P2_HOURS}} hours
+
+---
+
+### Phase 3: Backend Implementation
+
+**Files affected**:
+- `{{P3_FILE_1}}` — {{P3_CHANGE_DESC_1}}
+- `{{P3_FILE_2}}` — {{P3_CHANGE_DESC_2}}
+
+**Actions**:
+- [ ] Update API contract schema: `contracts/api/{{ENDPOINT}}/response.json`
+- [ ] Update handler to return `{{NEW_FIELD}}` in response
+- [ ] Add migration note to handler docstring
+- [ ] Validate: run integration tests for `{{ENDPOINT}}`
+
+**Estimated time**: {{P3_HOURS}} hours
+
+---
+
+### Phase 4: Client SDK
+
+**Files affected**:
+- `{{P4_FILE_1}}` — {{P4_CHANGE_DESC_1}}
+
+**Actions**:
+- [ ] Update TypeScript interface: `{{INTERFACE_NAME}}`
+  - Remove field: `{{REMOVED_FIELD}}: {{OLD_TYPE}}`
+  - Add field: `{{NEW_FIELD}}: {{NEW_TYPE}}`
+- [ ] Update serialization/deserialization if needed
+- [ ] Add deprecation warning for removed field (if migration window active)
+- [ ] Validate: run `tsc --noEmit` (no type errors)
+
+**Estimated time**: {{P4_HOURS}} hours
+
+---
+
+### Phase 5: E2E Tests
+
+**Files affected**:
+- `{{P5_FILE_1}}` — {{P5_CHANGE_DESC_1}}
+
+**Actions**:
+- [ ] Update scenario that checks `{{REMOVED_FIELD}}`
+- [ ] Add scenario for `{{NEW_FIELD}}` behavior
+- [ ] Validate: run `npx playwright test {{P5_TEST_PATTERN}}`
+
+**Estimated time**: {{P5_HOURS}} hours
+
+---
+
+## Migration Strategy
+
+### Recommended Execution Order
+
+```
+1. ✅ Phase 1: Contract updated (source of change)
+2. → Phase 2: Update test mocks and assertions (est. {{P2_HOURS}} h)
+3. → Phase 3: Update backend handler + response schema (est. {{P3_HOURS}} h)
+4. → Phase 4: Update client SDK types (est. {{P4_HOURS}} h)
+5. → Phase 5: Update E2E test scenarios (est. {{P5_HOURS}} h)
+
+Total estimated: {{TOTAL_HOURS}} hours
+```
+
+### Topological Sort (Dependency Order)
+
+```
+Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5
+```
+Phases must be updated in this order to avoid downstream breakage.
+
+### Rollback Plan
+
+If propagation fails at any phase:
+
+```bash
+# Rollback Phase 2 only (if Phase 2 update broke tests):
+git revert HEAD -- .planning/features/{{PHASE2_FEATURE}}/
+npm test  # verify passing again
+
+# Rollback entire change (if cascading failures):
+git revert <propagation-commit>
+# Then manually review the spec change requirement before re-attempting
+```
+
+---
+
+## Auto-Generated Updates Log
+
+| File | Update Type | Status | Timestamp |
+|------|------------|--------|-----------|
+| `{{FILE_1}}` | Mock data updated | {{STATUS_1}} | {{TS_1}} |
+| `{{FILE_2}}` | Type definition updated | {{STATUS_2}} | {{TS_2}} |
+| `{{FILE_3}}` | Contract schema updated | {{STATUS_3}} | {{TS_3}} |
+| `{{FILE_4}}` | Assertion updated | {{STATUS_4}} | {{TS_4}} |
+| `SPEC_CHANGELOG.md` | Entry appended | {{CHANGELOG_STATUS}} | {{CHANGELOG_TS}} |
+
+---
+
+## Validation Results
+
+### Pre-Commit Checklist
+
+- [ ] **Syntax check**: All updated files are valid JSON/JS/TS
+- [ ] **Contract alignment**: Updated contracts match actual changes
+- [ ] **Test consistency**: Updated tests are semantically correct
+- [ ] **Type safety**: Phase 4 types match Phase 3 API contract
+- [ ] **Cross-phase validation**:
+  - [ ] Phase 3 types ⊆ Phase 4 client types
+  - [ ] Phase 2 test data matches Phase 3 API contract
+  - [ ] Phase 5 tests reference existing Phase 4 client methods
+- [ ] **SPEC_CHANGELOG.md**: Entry added with correct severity
+- [ ] **Migration guide**: Created (required for BREAKING changes)
+
+### Test Run Results
+
+```
+Phase 2 tests: {{P2_TEST_RESULT}}
+Phase 3 tests: {{P3_TEST_RESULT}}
+Phase 4 type check: {{P4_TYPE_RESULT}}
+Phase 5 tests: {{P5_TEST_RESULT}}
+```
+
+---
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|-----------|
+| Phase 4 clients break on `{{REMOVED_FIELD}}` | {{LIKELIHOOD_1}} | {{IMPACT_1}} | {{MITIGATION_1}} |
+| Timeline slippage if Phase 3 complex | {{LIKELIHOOD_2}} | {{IMPACT_2}} | {{MITIGATION_2}} |
+| Circular dependency in phase updates | {{LIKELIHOOD_3}} | {{IMPACT_3}} | {{MITIGATION_3}} |
+
+---
+
+## SPEC_CHANGELOG.md Entry (Auto-Appended)
+
+```
+- {{DATE}} | {{CHANGE_TYPE}} | {{CHANGE_SUMMARY_ONE_LINER}}
+  Changed: {{CHANGED_FILE}} → {{CHANGED_SECTION}}
+  Affected: Phase {{AFFECTED_PHASES}} | Migration guide: {{MIGRATION_GUIDE_LINK}}
+  Auto-updated phases: {{AUTO_UPDATED_PHASES}} | Manual review: {{MANUAL_REVIEW}}
+```
+
+---
+
+## Sign-Off
+
+- [ ] **Developer review**: Impact report reviewed and accurate
+- [ ] **Auto-updates validated**: Changes look correct, no unintended modifications
+- [ ] **Tests passing**: All affected phase tests green
+- [ ] **Migration guide complete**: (required if BREAKING)
+- [ ] **Ready to proceed**: All downstream phases aligned
+
+**Reviewed by**: ________________________  
+**Date**: {{DATE}}  
+**Status**: [ ] APPROVED TO PROCEED | [ ] NEEDS REWORK | [ ] ESCALATE
+
+---
+
+*Generated by spec-impact-engine v1.0 | Genesis Codex Harness*