codex-genesis-harness 0.1.0 → 0.1.4

package/.codex/skills/genesis-spec-propagation/checklists/phase-update-verification.md

@@ -0,0 +1,384 @@
+# Phase-Specific Update Verification
+
+Verify that each phase was updated correctly after automatic propagation.
+
+---
+
+## Phase 2: Test Updates
+
+### Checklist: Test Mocks Updated
+
+- [ ] Mock data file identified: `tests/fixtures/mocks/*.js`
+- [ ] Old mock data removed (if breaking)
+- [ ] New mock data structure matches API spec
+- [ ] All required fields in mocks
+- [ ] Optional fields handled correctly
+- [ ] Test data types match API response types
+
+**Example**:
+```javascript
+// Before propagation
+const mockUser = {
+  id: 1,
+  name: 'John',
+  avatar: '/avatar.png'  // This was removed
+};
+
+// After propagation
+const mockUser = {
+  id: 1,
+  name: 'John'
+  // avatar removed - matches new API spec
+};
+```
+
+### Checklist: Test Assertions Updated
+
+- [ ] Assertions check new fields (if feature change)
+- [ ] Assertions removed for deleted fields (if breaking)
+- [ ] Type assertions match new types
+- [ ] Optional vs required assertions correct
+- [ ] Test descriptions updated
+
+**Example**:
+```javascript
+// Before
+expect(response.avatar).toBeDefined();
+expect(response.avatar).toMatch(/^\/\w+\.png$/);
+
+// After (avatar removed)
+expect(response).not.toHaveProperty('avatar');
+```
+
+### Checklist: Test Descriptions
+
+- [ ] Test descriptions match new spec
+- [ ] Comments explain new test scenarios
+- [ ] "What changed" explained in test comments
+- [ ] No outdated comments about removed fields
+
+### Validation
+
+```bash
+# Run Phase 2 tests
+npm test -- tests/
+# All tests passing? ✅
+```
+
+---
+
+## Phase 3: Backend Contract Updates
+
+### Checklist: API Contract Schema
+
+- [ ] Contract file identified: `contracts/api/response.json`
+- [ ] Schema matches new API spec exactly
+- [ ] New fields added (if feature)
+- [ ] Old fields removed (if breaking)
+- [ ] Field types correct
+- [ ] Required vs optional correct
+- [ ] Validation rules updated
+- [ ] Comments/descriptions updated
+
+**Example**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "integer" },
+    "name": { "type": "string" },
+    // "avatar" removed - breaking change
+    "email": { "type": "string", "format": "email" }  // new optional
+  },
+  "required": ["id", "name"]  // avatar removed from required
+}
+```
+
+### Checklist: Database Schema
+
+If database schema affected:
+- [ ] Schema change identified in `contracts/db/schema.json`
+- [ ] Migration script generated (if breaking)
+- [ ] Backward compatibility considered (if applicable)
+- [ ] Indexes updated (if necessary)
+- [ ] Rollback procedure documented
+
+### Checklist: Implementation Docstring
+
+- [ ] Handler docstring updated with new parameters
+- [ ] Response structure documented correctly
+- [ ] Breaking changes noted in docstring
+- [ ] Migration path mentioned (if breaking)
+
+**Example**:
+```javascript
+/**
+ * GET /api/users/:id
+ * 
+ * Returns user data (v2 format).
+ * 
+ * BREAKING CHANGE (v2): Field 'avatar' removed. Use 'avatarUrl' instead.
+ * Migration: https://docs.example.com/migration-v1-to-v2
+ * 
+ * Response: { id, name, avatarUrl?, email? }
+ */
+handler.get('/users/:id', (req, res) => { ... });
+```
+
+### Validation
+
+```bash
+# Validate API contract
+npm run validate:contracts
+
+# Type check
+npm run tsc --noEmit
+
+# All valid? ✅
+```
+
+---
+
+## Phase 4: Client SDK Updates
+
+### Checklist: Type Definitions
+
+- [ ] Type file identified: `types/api.ts`
+- [ ] Interface definition matches API contract
+- [ ] New fields added with correct types (if feature)
+- [ ] Old fields removed (if breaking)
+- [ ] Optional vs required correct
+- [ ] Union types updated if applicable
+
+**Example**:
+```typescript
+// Before
+interface User {
+  id: number;
+  name: string;
+  avatar: string;
+}
+
+// After
+interface User {
+  id: number;
+  name: string;
+  avatarUrl?: string;  // Optional, new field
+  email?: string;      // Optional, new field
+  // avatar removed
+}
+```
+
+### Checklist: Client Methods
+
+- [ ] Client method signatures updated (if breaking)
+- [ ] Return types match new API contract
+- [ ] Parameter types updated
+- [ ] Optional parameters marked correctly
+
+**Example**:
+```typescript
+// Before
+fetchUser(id: number): Promise<User & { avatar: string }> { ... }
+
+// After
+fetchUser(id: number): Promise<User> { ... }
+// avatar removed from return type
+```
+
+### Checklist: Serialization/Deserialization
+
+- [ ] Serialization logic updated (request → API)
+- [ ] Deserialization logic updated (API → client)
+- [ ] Field mapping updated if breaking
+- [ ] Type casting correct
+
+### Checklist: Deprecation Warnings (BREAKING ONLY)
+
+- [ ] Deprecation notice added to affected methods
+- [ ] Migration path documented
+- [ ] Timeline for removal specified
+- [ ] Alternative methods suggested
+
+**Example**:
+```typescript
+/**
+ * @deprecated Use fetchUser() instead, avatar field removed in v2
+ * Migration: https://docs.example.com/migration-v1-to-v2
+ * Removal date: 2026-12-31
+ */
+fetchUserWithAvatar(id: number): Promise<User> { ... }
+```
+
+### Validation
+
+```bash
+# Type check
+npm run tsc --noEmit
+
+# Any type errors? ❌
+# All types valid? ✅
+```
+
+---
+
+## Phase 5: E2E Test Updates
+
+### Checklist: Scenario Files
+
+- [ ] Scenario file identified: `playwright/e2e/scenarios.md`
+- [ ] New scenarios added for new fields (if feature)
+- [ ] Old scenarios removed or updated (if breaking)
+- [ ] Scenarios reference correct Phase 4 SDK methods
+- [ ] Test data matches updated spec
+
+**Example**:
+```markdown
+## Create User with Email
+
+- Input: { name: "John", email: "john@example.com" }
+- Expected: User created with email field
+- ❌ Removed: "Create User with Avatar" (avatar removed in v2)
+```
+
+### Checklist: E2E Assertions
+
+- [ ] Assertions check new fields (if feature)
+- [ ] Assertions removed for deleted fields (if breaking)
+- [ ] Assertions match new API response structure
+- [ ] Element selectors still valid (if UI affected)
+
+**Example**:
+```javascript
+// Before
+page.locator('[data-test="user-avatar"]').isVisible()
+
+// After (avatar removed from UI)
+page.locator('[data-test="user-avatar"]').isHidden()
+// OR removed entirely if no UI replacement
+```
+
+### Checklist: Test Data
+
+- [ ] Test data fixtures match new API spec
+- [ ] Mock responses updated if needed
+- [ ] Page objects reference updated fields
+- [ ] Helper functions updated
+
+### Checklist: Page Objects
+
+- [ ] Page object selectors match updated UI
+- [ ] Methods return correct data types
+- [ ] No references to removed fields
+
+### Validation
+
+```bash
+# Run E2E tests (subset to verify updates)
+npm run test:e2e -- --grep "User"
+
+# All E2E tests passing? ✅
+```
+
+---
+
+## Cross-Phase Consistency Check
+
+After all phases updated, verify they're still aligned.
+
+### Type System Alignment
+
+- [ ] Phase 3 API contract types ⊂ Phase 4 SDK types?
+- [ ] Phase 2 test data types match Phase 3 API response?
+- [ ] Phase 5 test data types match Phase 4 SDK input?
+
+**Check**: Types shouldn't require conversion between phases
+
+### Data Flow Alignment
+
+```
+Phase 2: Mock data
+    ↓ (matches)
+Phase 3: API response schema
+    ↓ (matches)
+Phase 4: Client type definitions
+    ↓ (matches)
+Phase 5: E2E test expectations
+```
+
+- [ ] Mock → API Contract: Same fields & types
+- [ ] API Contract → Client Types: Same structure
+- [ ] Client Types → E2E Tests: Same data
+
+### Method Call Alignment
+
+- [ ] Phase 5 E2E calls Phase 4 methods correctly
+- [ ] Phase 4 SDK methods call Phase 3 endpoints correctly
+- [ ] Phase 2 tests verify same behavior as Phase 3
+
+### Validation
+
+```bash
+# Run all tests together
+npm run test:full
+
+# No integration errors? ✅
+# No type mismatches? ✅
+```
+
+---
+
+## Conflict Resolution
+
+If any phase is out of sync with others, document the conflict.
+
+### Conflict Recording
+
+Create `CONFLICT_LOG.md` entry:
+
+```markdown
+## Conflict: Phase 3 ↔ Phase 4 Type Mismatch
+
+**Date**: 2026-05-31
+**Severity**: HIGH
+**Change**: API response removed 'avatar' field
+
+**Conflict Details**:
+- Phase 3 API contract: { id, name, email } ✓
+- Phase 4 SDK types: { id, name, avatar, email } ✗
+- Mismatch: avatar field in SDK but not in API
+
+**Resolution**:
+1. Remove avatar from Phase 4 types
+2. Add deprecation warning
+3. Re-run validation
+
+**Status**: RESOLVED
+```
+
+### Manual Intervention
+
+If conflicts found:
+1. **Identify**: Which phases are misaligned?
+2. **Cause**: Why did propagation miss this?
+3. **Fix**: Manual update to misaligned phase
+4. **Document**: Add to CONFLICT_LOG.md
+5. **Re-validate**: Run tests again
+6. **Improve**: Update patterns to prevent recurrence
+
+---
+
+## Sign-Off Checklist
+
+Once all updates complete and validated:
+
+- [ ] Phase 2 tests: All green ✅
+- [ ] Phase 3 contract: Valid & aligned ✅
+- [ ] Phase 4 SDK: Types correct & synchronized ✅
+- [ ] Phase 5 E2E: Tests pass & scenarios updated ✅
+- [ ] Cross-phase consistency: Verified ✅
+- [ ] No conflicts: All aligned ✅
+- [ ] Migration guide: Complete (if breaking) ✅
+- [ ] SPEC_CHANGELOG.md: Entry added ✅
+- [ ] Ready for commit ✅
+

package/.codex/skills/genesis-spec-propagation/checklists/spec-change-detection.md

@@ -0,0 +1,257 @@
+# Spec Change Detection Checklist
+
+## Pre-Propagation Verification
+
+Verify before starting automatic propagation.
+
+### 1. Change Documentation ✓
+
+- [ ] Change is well-documented (why changed, impact)
+- [ ] Old spec vs new spec available for comparison
+- [ ] Change type identified (breaking/feature/non-impact)
+- [ ] SPEC_CHANGELOG.md entry created (if not, auto-append)
+
+### 2. Change Validity
+
+- [ ] Change is intentional (not a mistake)
+- [ ] Change doesn't introduce new technical debt
+- [ ] Change is aligned with project architecture
+- [ ] Change doesn't violate any contracts or constraints
+
+**If any "No"**: STOP propagation, review change with team before continuing.
+
+---
+
+## Change Type Classification
+
+Classify the change before propagation determines update strategy.
+
+### BREAKING CHANGE
+
+**Indicators**:
+- ❌ Removed field from API response
+- ❌ Changed field type (number → string, optional → required)
+- ❌ Removed database column
+- ❌ Changed endpoint URL or method
+- ❌ Changed validation rule (stricter or behavioral change)
+- ❌ Renamed field
+
+**Examples**:
+```diff
+- { "userId": 123 }  →  { "id": 123 }  // Renamed field
+- { "status": "active" }  →  { "status": 1 }  // Type changed
++ { "email": "required" }  // Made required when optional
+```
+
+**Propagation Complexity**: HIGH (manual review recommended)
+**Downstream Impact**: Major (all phases affected)
+**Time to Update**: 2-4 hours (includes design decisions)
+
+---
+
+### FEATURE CHANGE
+
+**Indicators**:
+- ✅ Added new optional field to API response
+- ✅ Added new optional parameter to function
+- ✅ Added new endpoint or operation
+- ✅ Added new validation (optional field)
+- ✅ Extended enum with new value
+- ✅ Made field optional (was required)
+
+**Examples**:
+```diff
++ { "avatarUrl": "https://..." }  // New optional field
++ { "tags": [] }  // New optional array
++ POST /api/users/export  // New endpoint
++ "status" in ["active", "inactive", "archived"]  // Extended enum
+```
+
+**Propagation Complexity**: MEDIUM (mostly automatic)
+**Downstream Impact**: Moderate (Phase 2, 3, 5 affected)
+**Time to Update**: 30-60 minutes
+
+---
+
+### NON-IMPACT CHANGE
+
+**Indicators**:
+- 📝 Updated description/documentation
+- 📝 Updated example values
+- 📝 Formatting/styling change
+- 📝 Reordered fields (same data)
+- 📝 Updated comment (code, not logic)
+
+**Examples**:
+```diff
+- "description": "User name"  →  "description": "Full name of user"
+- { "id": 1, "name": "John" }  →  { "name": "John", "id": 1 }  // Reordered
+- 200  →  200  // Same HTTP status, just reformatted
+```
+
+**Propagation Complexity**: LOW (minimal updates)
+**Downstream Impact**: Minimal (maybe Phase 2 only for docs)
+**Time to Update**: 5-10 minutes
+
+---
+
+## Affected Phase Detection Checklist
+
+Verify the right phases are identified as affected.
+
+### Phase 2: Tests
+- [ ] Test mocks need updating? (breaking/feature)
+- [ ] Test data needs updating? (breaking/feature)
+- [ ] Test assertions need updating? (breaking)
+- [ ] Affected test file identified?
+
+### Phase 3: Backend Implementation
+- [ ] API contract changes? (all types)
+- [ ] Response builder affected? (breaking/feature)
+- [ ] Request validation affected? (breaking)
+- [ ] Database schema affected? (breaking - migration needed)
+- [ ] Handler docstring needs update? (breaking)
+
+### Phase 4: Client SDK
+- [ ] Client method signatures affected? (breaking)
+- [ ] Type definitions need update? (breaking/feature)
+- [ ] Serialization logic affected? (breaking)
+- [ ] Deprecation warnings needed? (breaking)
+
+### Phase 5: E2E Tests
+- [ ] E2E scenarios need new test cases? (feature)
+- [ ] E2E assertions need updating? (breaking)
+- [ ] E2E data needs updating? (breaking/feature)
+- [ ] New scenarios for new fields? (feature)
+
+**Validation**: At least Phase 2 OR Phase 3 should be "Yes" for any change.
+
+---
+
+## Dependency Path Verification
+
+Confirm propagation order is correct (topological sort).
+
+### Valid Propagation Order
+
+1. **Phase 1**: Original spec change ✅
+2. **Phase 2**: Tests updated (independent of implementation)
+3. **Phase 3**: Backend implementation aligned with updated tests
+4. **Phase 4**: Client SDK updated to match Phase 3 API
+5. **Phase 5**: E2E tests updated to use Phase 4 SDK + Phase 3 API
+
+### Order Validation Checklist
+
+- [ ] Phase 2 updates don't depend on Phase 3 changes (true for mocks)
+- [ ] Phase 3 updates use Phase 2 tests as reference
+- [ ] Phase 4 updates don't precede Phase 3 (SDK depends on API)
+- [ ] Phase 5 updates reference Phase 4 SDK + Phase 3 API
+
+**If any violated**: Stop, reorder phases before propagation.
+
+---
+
+## Manual Update Trigger
+
+When should manual review override automatic updates?
+
+### Require Manual Review If...
+
+**CRITICAL TRIGGERS** (Stop propagation):
+- [ ] Breaking change + no clear migration path
+- [ ] Change affects 5+ files in Phase 3
+- [ ] Database migration needed (breaking + data loss risk)
+- [ ] API version bump needed (breaking)
+- [ ] SDK deprecation policy violated
+- [ ] Contract violates architectural constraint
+
+**RECOMMENDED REVIEW** (Proceed with caution):
+- [ ] Feature change affecting Phase 3 + Phase 4 together
+- [ ] Type system needs re-design (e.g., union type)
+- [ ] Performance implications (schema change, new indexes)
+- [ ] Security implication (new validation, encryption)
+
+**AUTOMATIC OK** (Can auto-propagate):
+- [ ] Optional field addition (feature)
+- [ ] Optional parameter addition (feature)
+- [ ] New endpoint (feature)
+- [ ] New enum value (feature)
+- [ ] Documentation update (non-impact)
+
+---
+
+## Conflict Detection Checklist
+
+Watch for conflicts during propagation.
+
+### Potential Conflicts
+
+**Phase 2 ↔ Phase 3**:
+- [ ] Phase 2 mocks outdated when Phase 3 was implemented?
+- [ ] Phase 3 handler not aligned with Phase 2 expectations?
+
+**Phase 3 ↔ Phase 4**:
+- [ ] Phase 4 SDK has workarounds for Phase 3 quirks?
+- [ ] Backward compatibility code in Phase 4 would break?
+
+**Phase 4 ↔ Phase 5**:
+- [ ] Phase 5 tests rely on deprecated Phase 4 methods?
+- [ ] Phase 5 hardcodes values from Phase 4 SDK?
+
+**All Phases**:
+- [ ] Any hardcoded values in tests/implementation?
+- [ ] Any duplicate data definitions (brittleness)?
+- [ ] Any circular dependencies?
+
+**If conflicts found**: Document in CONFLICT_LOG.md, escalate for manual resolution.
+
+---
+
+## Post-Propagation Validation
+
+After automatic updates, verify everything still works.
+
+### Syntax Validation
+
+- [ ] Phase 2 test files are valid JavaScript
+- [ ] Phase 3 contract files are valid JSON
+- [ ] Phase 4 type files are valid TypeScript
+- [ ] Phase 5 scenario files are valid Markdown
+
+### Semantic Validation
+
+- [ ] Phase 2 tests make logical sense (not just syntactically valid)
+- [ ] Phase 3 contract accurately describes new API
+- [ ] Phase 4 types match Phase 3 contract structure
+- [ ] Phase 5 scenarios reference Phase 4 SDK correctly
+
+### Integration Testing
+
+- [ ] Run Phase 2 tests: `npm test -- tests/`
+- [ ] Run Phase 3 validation: `npm run validate:contracts`
+- [ ] Run Phase 4 type check: `npm run tsc --noEmit`
+- [ ] Run Phase 5 E2E: `npm run test:e2e` (subset)
+
+### All Tests Green?
+
+- [ ] Yes → Propagation successful ✅
+- [ ] No → Identify failing tests, manual review needed ⚠️
+
+---
+
+## Migration Guide Checklist (BREAKING CHANGES ONLY)
+
+For breaking changes, verify migration guide is complete.
+
+- [ ] Migration guide file exists (e.g., `docs/migration-v2-to-v3.md`)
+- [ ] "What changed" section complete
+- [ ] "Why changed" section explains rationale
+- [ ] "Impact" section lists affected consumers
+- [ ] "Migration steps" are clear and step-by-step
+- [ ] "Timeline" specified (deprecation period, cutoff date)
+- [ ] "Rollback procedure" documented
+- [ ] "Backward compatibility period" specified (if any)
+- [ ] Examples of old vs new code provided
+
+**If migration guide incomplete**: Block commit until complete.
+

package/.codex/skills/genesis-spec-propagation/examples/example.md

@@ -0,0 +1,63 @@
+# Example: Propagating a Breaking API Change Across Phases
+
+## Scenario
+
+The Phase 1 API contract for `GET /api/users/:id` is updated to change the response:
+
+```
+Before: { name, email, role }
+After:  { id, name, email, roles[] }
+```
+
+This is a **BREAKING** change — `role` (string) is replaced by `roles[]` (array).
+
+## Trigger
+
+```
+/spec-change .planning/API_DOCS.md
+```
+
+Auto-triggered after `/spec-change` completes.
+
+## Phase 1: Change Detection (5 min)
+
+```
+Detected: BREAKING change in .planning/API_DOCS.md
+  - Removed field: role (string)
+  - Added field: roles (array)
+  - Affected section: GET /api/users/:id response
+```
+
+## Phase 2: Impact Analysis (10 min)
+
+```
+Dependency graph traced:
+  Phase 2 (Tests):   HIGH — 5 mock assertions use role field
+  Phase 3 (Backend): HIGH — response builder must return roles array
+  Phase 4 (SDK):     MEDIUM — interface User needs roles: string[]
+  Phase 5 (E2E):     LOW — update 2 role-checking scenarios
+```
+
+## Phase 3: Auto-Updates Applied (15 min)
+
+- **Phase 2** `tests/api-mocks.test.ts` — Updated `expect(response.role)` → `expect(response.roles[0])`
+- **Phase 3** `contracts/api/GetUser/response.json` — Schema updated to include `roles` array
+- **Phase 4** `types/api.ts` — `interface User { roles: string[] }` replacing `role: string`
+- **Phase 5** `playwright/e2e/user-profile.spec.ts` — Updated 2 role-check assertions
+
+## Migration Guide Generated
+
+```markdown
+## BREAKING: role → roles[] in GET /api/users/:id
+
+Migration: Replace `user.role` with `user.roles[0]` for primary role access.
+Timeline: Migrate before v3.0.0 release.
+```
+
+## Outcome
+
+- ✅ All 4 phases updated automatically
+- ✅ Tests re-run and passing
+- ✅ Migration guide created
+- ✅ SPEC_CHANGELOG.md entry added
+- ✅ 45 min manual work → 30 min automated