codex-genesis-harness 0.1.0 → 0.1.4

package/.codebase/RECOVERY_POINTS.md

@@ -0,0 +1,438 @@
+# Recovery Points
+
+**Purpose**: Document where implementation can be paused and resumed without losing context or creating inconsistencies.
+
+**Use When**: Work needs to be paused, passed to another developer, or interrupted by higher priority work.
+
+---
+
+## Quick Reference: Current Recovery Points
+
+| Phase | Status | Resumption File | Last Updated |
+|-------|--------|-----------------|--------------|
+| Planning | ✓ Complete | `.codebase/CURRENT_STATE.md` | _date_ |
+| Design | ✓ Complete | IMPLEMENTATION_HANDOFF.md | _date_ |
+| Contracts | ✓ Complete | `.codebase/API_CONTRACTS.md` | _date_ |
+| Tests | ⏸️ In Progress | `tests/auth.test.ts` | _date_ |
+| Implementation | ⏸️ In Progress | `src/auth/` | _date_ |
+| Documentation | ⏸️ Pending | `docs/AUTH.md` | _date_ |
+
+---
+
+## Phase: Planning
+
+**Status**: ✓ Complete  
+**Start Date**: _date_  
+**End Date**: _date_  
+**Resumption**: Not needed
+
+### What Happened
+
+All requirements gathered, validated, and documented.
+
+### To Resume (If Needed)
+
+Not applicable - planning is complete and locked.
+
+---
+
+## Phase: Design & Architecture
+
+**Status**: ✓ Complete  
+**Start Date**: _date_  
+**End Date**: _date_  
+**Resumption**: Not needed
+
+### What Happened
+
+System design completed, contracts defined, technology choices made.
+
+### Artifacts
+
+- `.codebase/ARCHITECTURE.md` - Final design
+- `.codebase/API_CONTRACTS.md` - API specifications
+- `IMPLEMENTATION_HANDOFF.md` - Design decisions
+
+### To Resume (If Needed)
+
+Not applicable - design is frozen and approved.
+
+---
+
+## Phase: Test Contracts & Fixtures
+
+**Status**: ✓ Complete  
+**Start Date**: _date_  
+**End Date**: _date_  
+**Resumption**: Not needed
+
+### What Happened
+
+Test contracts created, fixtures built, test infrastructure ready.
+
+### Artifacts
+
+```
+tests/
+├── contracts/
+│   ├── auth-api.contract.json
+│   └── session-manager.contract.json
+├── fixtures/
+│   ├── oauth-responses.json
+│   └── user-data.json
+└── setup/
+    ├── test-db-init.sql
+    └── mock-providers.ts
+```
+
+### To Resume (If Needed)
+
+Not applicable - test infrastructure is ready.
+
+---
+
+## Phase: Core Implementation (CURRENT PAUSE POINT)
+
+**Status**: ⏸️ In Progress (50% complete)  
+**Start Date**: _date_  
+**Current Date**: _YYYY-MM-DD_  
+**Estimated Completion**: _date_
+
+### What Was Done (Completed)
+
+```
+✓ src/auth/oauth-provider.ts
+  - OAuth 2.0 flow implementation
+  - Provider callback handling
+  - Token management
+
+✓ src/db/migrations/
+  - New users table fields
+  - oauth_provider, oauth_id columns
+
+✓ tests/auth.test.ts
+  - 15 tests written and passing
+  - 90% coverage of oauth-provider.ts
+```
+
+### What Remains (To Do)
+
+```
+⏳ src/auth/session-manager.ts
+  - Session creation and validation
+  - Session timeout handling
+  - Concurrent session management
+
+⏳ src/ui/pages/
+  - Login component
+  - Registration component
+  - Error handling UI
+
+⏳ API endpoints
+  - POST /auth/login
+  - POST /auth/register
+  - POST /auth/logout
+
+⏳ Integration tests
+  - End-to-end OAuth flow
+  - Database state consistency
+```
+
+### Pause State
+
+**What's Safe to Pause Here:**
+
+The OAuth provider module is isolated and complete. Can pause safely at this point.
+
+**Before Pausing:**
+
+```bash
+# 1. Commit current progress
+git add -A
+git commit -m "feat: OAuth provider implementation (50% complete)"
+
+# 2. Verify tests pass
+npm test
+
+# 3. Document pause point
+# (You are reading this file!)
+
+# 4. Create recovery checklist
+# (See section below)
+```
+
+### To Resume From Here
+
+**Step 1: Environment Setup** (5 min)
+
+```bash
+# Pull latest changes
+git pull origin main
+
+# Verify you're on the right branch
+git branch -v
+
+# Install dependencies
+npm install
+
+# Check database is migrated
+npm run db:status
+```
+
+**Step 2: Verify Previous Work** (5 min)
+
+```bash
+# Run existing tests
+npm test -- auth.test.ts
+# Expected: 15 passing
+
+# Check module compiles
+npm run build
+
+# Verify no uncommitted changes
+git status
+```
+
+**Step 3: Review What's Next** (10 min)
+
+```bash
+# Read the handoff document
+cat IMPLEMENTATION_HANDOFF.md
+
+# Check what was planned next
+cat .codebase/CURRENT_STATE.md
+
+# Review test contract
+cat tests/contracts/auth-api.contract.json
+```
+
+**Step 4: Resume Implementation** (30 min+)
+
+Start with session-manager.ts:
+
+```bash
+# Create new branch (if needed)
+git checkout -b continue/auth-session
+
+# Open the next module
+code src/auth/session-manager.ts
+
+# Reference the test contract
+code tests/contracts/session-manager.contract.json
+
+# Start implementing...
+```
+
+---
+
+## Phase: Session Management (NEXT PHASE)
+
+**Status**: ⏳ Ready to start  
+**Estimated Start**: _date_  
+**Estimated Duration**: 4-6 hours  
+**Estimator**: Original developer
+
+### What Needs to Happen
+
+1. **Implement session-manager.ts**
+   - Create session on login
+   - Validate session on requests
+   - Handle timeout
+
+2. **Write session tests**
+   - Session creation tests
+   - Validation tests
+   - Timeout tests
+   - Concurrent session tests
+
+3. **Update database**
+   - Add sessions table migration
+   - Add indexes for performance
+
+### Acceptance Criteria
+
+```
+- [ ] Session manager module complete
+- [ ] 12+ session tests written and passing
+- [ ] Coverage ≥ 85%
+- [ ] No performance regressions
+- [ ] Integrated with OAuth provider
+```
+
+### Dependencies
+
+- ✓ OAuth provider complete (already done)
+- ✓ Database migrations (already done)
+- ⏳ Needs: Node.js session library installed
+
+### Blockers
+
+None identified. Ready to proceed.
+
+---
+
+## Phase: UI Components (AFTER SESSION)
+
+**Status**: ⏳ Ready to start  
+**Estimated Start**: _date_ (after session phase)  
+**Estimated Duration**: 6-8 hours
+
+### What Needs to Happen
+
+1. **Build Login Page**
+   - OAuth provider buttons
+   - Error messaging
+   - Loading states
+
+2. **Build Register Page**
+   - Form validation
+   - Provider linking
+   - Success messaging
+
+3. **Update Layout**
+   - Add auth header
+   - Add logout button
+   - Add user menu
+
+### Files to Modify
+
+```
+src/ui/pages/
+├── login.tsx (new)
+├── register.tsx (new)
+└── layout.tsx (modify)
+
+src/ui/components/
+├── oauth-button.tsx (new)
+├── auth-error.tsx (new)
+└── user-menu.tsx (modify)
+
+styles/
+├── auth.css (new)
+```
+
+### Acceptance Criteria
+
+```
+- [ ] Login page working
+- [ ] Register page working
+- [ ] OAuth provider flow works E2E
+- [ ] Error messages display correctly
+- [ ] Mobile responsive
+- [ ] Browser compatibility tested
+```
+
+---
+
+## Phase: Documentation & Testing (FINAL PHASE)
+
+**Status**: ⏳ Ready to start  
+**Estimated Start**: _date_ (after UI phase)  
+**Estimated Duration**: 4 hours
+
+### What Needs to Happen
+
+1. **Update Documentation**
+   - README auth section
+   - Setup guide
+   - API documentation
+   - Troubleshooting guide
+
+2. **Final Testing**
+   - Full E2E test suite
+   - Performance testing
+   - Security testing
+   - Browser compatibility
+
+3. **Code Review & QA**
+   - Team code review
+   - QA testing
+   - Security review
+
+### Acceptance Criteria
+
+```
+- [ ] All documentation complete
+- [ ] All E2E tests passing
+- [ ] Code review approved
+- [ ] No security issues
+- [ ] Performance acceptable
+- [ ] Ready for production
+```
+
+---
+
+## Rollback Points
+
+### If Implementation Gets Stuck
+
+**Rollback Level 1: Last Commit**
+```bash
+git reset --hard HEAD
+npm install
+npm test  # Should pass
+```
+
+**Rollback Level 2: Before This Feature**
+```bash
+git checkout main
+npm install
+npm test
+# Verify everything works on main
+```
+
+**Rollback Level 3: Database Rollback**
+```bash
+npm run db:rollback -- auth-v1
+# Removes auth tables/fields
+# App reverts to state before auth changes
+```
+
+---
+
+## Checklist: Before Pausing Work
+
+- [ ] All current tests passing
+- [ ] Code builds without errors
+- [ ] No uncommitted changes
+- [ ] Commit message written (describe state)
+- [ ] This Recovery Points file updated
+- [ ] Next developer notified
+- [ ] Slack message sent with status
+
+---
+
+## Checklist: When Resuming Work
+
+- [ ] Pull latest git changes
+- [ ] Run `npm install` (if dependencies changed)
+- [ ] Run existing tests (verify they still pass)
+- [ ] Read IMPLEMENTATION_HANDOFF.md
+- [ ] Read this Recovery Points file
+- [ ] Update status in this file (what phase are you on?)
+- [ ] Begin implementation from current phase
+
+---
+
+## Known Issues That Might Affect Resumption
+
+| Issue | Severity | Workaround | Fixed? |
+|-------|----------|-----------|--------|
+| OAuth token refresh timing | Low | Add 5s buffer | ⏳ TODO |
+| Database connection pooling | Medium | Use pool size 10 | ✓ Fixed |
+| Rate limiting missing | Low | Not blocking | ⏳ TODO |
+
+---
+
+## Contact For Questions
+
+**Original Developer**: _Name_ (_email_)  
+**Current Owner**: _Name_ (_email_)  
+**Slack Channel**: #auth-feature  
+
+---
+
+**Last Updated**: _YYYY-MM-DD HH:MM_  
+**Updated By**: _Name_  
+**Next Review**: _YYYY-MM-DD_  
+**Paused At**: _Phase: Core Implementation_

package/.codebase/TEST_MATRIX.md

@@ -0,0 +1,11 @@
+# Test Matrix
+
+Required checks:
+
+- `scripts/verify.sh`: repository harness structure, skill metadata, contracts, fixtures, and harness smoke test.
+- `scripts/run-evals.sh`: install/verify/uninstall regression checks.
+- `npm run pack:check`: package contents dry-run.
+- Skill validation: run `quick_validate.py` for changed skills when available.
+
+Feature rule: add or update fixtures and expected output before implementation.
+

package/.codebase/UI_ROUTES.md

@@ -0,0 +1,4 @@
+# UI Routes
+
+This package has no runtime UI routes. UI harness templates live under `playwright/` for downstream projects using Genesis skills.
+

package/.codebase/context/backend-summary.md

@@ -0,0 +1,4 @@
+# Backend Summary
+
+No backend service is implemented in this package. Backend guidance is represented by contracts, fixtures, and test templates for downstream repositories.
+

package/.codebase/context/frontend-summary.md

@@ -0,0 +1,4 @@
+# Frontend Summary
+
+No frontend app is implemented here. Frontend workflows are provided through `genesis-new-design`, `genesis-upgrade-design`, design-spec, and Playwright templates.
+

package/.codebase/context/pipeline-summary.md

@@ -0,0 +1,4 @@
+# Pipeline Summary
+
+The harness pipeline is test-first and contract-first: memory read, failing test, fixture, implementation, verification, contracts, memory, docs, summary.
+

package/.codebase/context/providers-summary.md

@@ -0,0 +1,4 @@
+# Providers Summary
+
+AI providers are represented by contracts and fixtures. Provider-specific code should be tested through mock providers, retry tests, invalid JSON recovery tests, and persistence checks.
+

package/.codebase/context/render-summary.md

@@ -0,0 +1,4 @@
+# Render Summary
+
+Render workflows are represented by fixtures under `fixtures/render/` and contracts for render agents. Downstream render implementations must validate input, output, and failure artifacts.
+

package/.codebase/context/tests-summary.md

@@ -0,0 +1,4 @@
+# Tests Summary
+
+Use `scripts/verify.sh`, `scripts/run-evals.sh`, skill validation, contract tests, integration tests, unit tests, and Playwright smoke/e2e/visual templates.
+

package/.codex/skills/genesis-ai-provider/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ai-provider-skill
+description: Define reliable AI provider harnesses with mock providers, schemas, retries, invalid JSON recovery, persistence tests, and provider contracts. Use for LLM, image, voice, subtitle, render, and pipeline provider work.
+---
+
+# AI Provider Skill
+
+## Purpose
+Make AI provider behavior deterministic under tests and recoverable under failures.
+
+## When to use
+Use before adding or changing AI providers, provider adapters, retry logic, schema parsing, or persistence.
+
+## When NOT to use
+Do not use for purely static documentation changes.
+
+## Inputs required
+Provider name, request shape, expected response, error modes, retry policy, and persistence target.
+
+## Outputs required
+Provider contract, mock provider fixture, schema validation, retry test, invalid JSON recovery test, and persistence test.
+
+## Required tests
+Mock success, provider error, retry, invalid JSON recovery, and persistence tests.
+
+## Required fixtures
+Create provider fixtures under `fixtures/agents`, `fixtures/images`, `fixtures/tts`, or related directories.
+
+## Required contract updates
+Update `contracts/agents/` or provider-specific contracts.
+
+## Required codebase map updates
+Update providers summary, pipeline flow, and test matrix.
+
+## Token saving rules
+Read provider summary and contract before provider code.
+
+## Acceptance criteria
+Provider output is schema-validated and failure recovery is tested.
+
+## Common mistakes
+Trusting raw model JSON, skipping retry tests, and using live provider calls in normal tests.
+
+## Recovery workflow
+If provider output is invalid, capture fixture, add parser recovery test, then patch parser or contract.
+

package/.codex/skills/genesis-ai-provider/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "AI Provider Skill"
+  short_description: "Harden AI provider contracts and tests"
+  default_prompt: "Use $ai-provider-skill to define provider contracts, fixtures, and recovery tests."
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/genesis-ai-provider/checklists/checklist.md

@@ -0,0 +1,9 @@
+# AI Provider Checklist
+
+- [ ] Mock provider.
+- [ ] Fixture input.
+- [ ] Expected JSON output.
+- [ ] Schema validation.
+- [ ] Retry and invalid JSON tests.
+- [ ] Persistence test.
+

package/.codex/skills/genesis-ai-provider/examples/example.md

@@ -0,0 +1,4 @@
+# Example
+
+Mock image generation provider output, validate schema, retry transient failure, and persist artifact metadata.
+

package/.codex/skills/genesis-ai-provider/templates/provider-contract-template.md

@@ -0,0 +1,9 @@
+# Provider Contract Template
+
+## Request
+## Response
+## Validation
+## Retry Policy
+## Persistence
+## Failure Modes
+

package/.codex/skills/genesis-api-contract/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: api-contract-skill
+description: Create and verify API contracts before endpoint implementation. Use for API routes, service interfaces, validation rules, error shapes, snapshots, and endpoint tests.
+---
+
+# API Contract Skill
+
+## Purpose
+Ensure API behavior is defined by contracts, fixtures, and tests before code.
+
+## When to use
+Use before adding or changing endpoints, request schemas, response schemas, auth, errors, or persistence behavior.
+
+## When NOT to use
+Do not use for UI-only changes that do not touch API behavior.
+
+## Inputs required
+Endpoint path, method, auth, request body, success response, error cases, and persistence effects.
+
+## Outputs required
+Contract folder, fixture, success test, validation error test, not found test, and schema validation.
+
+## Required tests
+Create contract, integration, and unit tests as appropriate.
+
+## Required fixtures
+Create API fixtures for success and failure cases.
+
+## Required contract updates
+Update `contracts/api/` with request, response, schema, example, and error JSON.
+
+## Required codebase map updates
+Update `.codebase/API_CONTRACTS.md` and `TEST_MATRIX.md`.
+
+## Token saving rules
+Load endpoint contract before source files. Open only route and validator modules named by the contract.
+
+## Acceptance criteria
+Contract tests fail before implementation and pass after the minimum endpoint change.
+
+## Common mistakes
+Implementing validation before schema, changing error shape without a contract, and testing only success.
+
+## Recovery workflow
+If endpoint behavior is ambiguous, freeze implementation and create the missing contract first.
+

package/.codex/skills/genesis-api-contract/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "API Contract Skill"
+  short_description: "Define API contracts before endpoints"
+  default_prompt: "Use $api-contract-skill to create endpoint contracts and tests before implementation."
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/genesis-api-contract/checklists/checklist.md

@@ -0,0 +1,8 @@
+# API Contract Checklist
+
+- [ ] Request schema exists.
+- [ ] Response schema exists.
+- [ ] Error schema exists.
+- [ ] Fixture exists.
+- [ ] Contract test fails first.
+

package/.codex/skills/genesis-api-contract/examples/example.md

@@ -0,0 +1,4 @@
+# Example
+
+Before adding `POST /api/jobs`, create request, response, schema, example, error, and contract tests.
+

package/.codex/skills/genesis-api-contract/templates/api-contract-template.md

@@ -0,0 +1,4 @@
+# API Contract Template
+
+Use `contracts/api/endpoint-template/` and replace path, method, schema, examples, and errors.
+