codex-genesis-harness 0.1.0 → 0.1.4

package/.codex/skills/genesis-api-sync/templates/api-change-template.md

@@ -0,0 +1,257 @@
+# API Sync Template
+
+## Endpoint Change Report
+
+### Metadata
+
+- **Feature/Change**: _[Name]_
+- **Date**: _YYYY-MM-DD_
+- **Author**: _Name_
+- **Breaking Changes**: ☐ Yes / ☐ No
+- **Version Impact**: ☐ Patch / ☐ Minor / ☐ Major
+
+---
+
+## Changed Endpoints
+
+### [1] NEW ENDPOINT
+
+```
+Method: GET
+Path: /api/v1/resource
+Status: NEW in v1.0
+```
+
+**Request:**
+```json
+{
+  "query": {
+    "page": "number (optional, default: 1)",
+    "limit": "number (optional, default: 20)"
+  }
+}
+```
+
+**Response 200:**
+```json
+{
+  "data": [
+    {
+      "id": "string",
+      "name": "string",
+      "created_at": "ISO-8601 timestamp"
+    }
+  ],
+  "pagination": {
+    "page": "number",
+    "limit": "number",
+    "total": "number"
+  }
+}
+```
+
+**Error Responses:**
+- `400 Bad Request`: Invalid query parameters
+- `401 Unauthorized`: Missing authentication
+- `500 Server Error`: Internal server error
+
+**Auth Required:** Yes - Bearer token in `Authorization` header
+
+**Rate Limit:** 100 requests/hour per API key
+
+---
+
+### [2] MODIFIED ENDPOINT
+
+```
+Method: POST
+Path: /api/v1/resource
+Status: MODIFIED in v1.2
+Previous Version: v1.1
+```
+
+**Changes:**
+```diff
+- Removed field: `legacy_field`
++ Added field: `new_field` (required)
+- Changed: `status` enum values
+```
+
+**Request (v1.2):**
+```json
+{
+  "name": "string (required)",
+  "email": "string (required, email format)",
+  "new_field": "string (required)",
+  "optional_data": "object (optional)"
+}
+```
+
+**Response 201:**
+```json
+{
+  "id": "string",
+  "name": "string",
+  "email": "string",
+  "new_field": "string",
+  "created_at": "ISO-8601 timestamp",
+  "status": "active | inactive | pending"
+}
+```
+
+**Breaking Changes:**
+- ✗ `legacy_field` removed - clients using this will break
+- ✓ `new_field` required - endpoint will reject requests without it
+- ✓ `status` values changed - parsing logic needs update
+
+---
+
+### [3] DEPRECATED ENDPOINT
+
+```
+Method: DELETE
+Path: /api/v1/resource/{id}
+Status: DEPRECATED
+Removal Date: 2026-09-30
+Replacement: DELETE /api/v2/resource/{id}
+```
+
+**Deprecation Notice:**
+```
+⚠️  This endpoint will be removed on 2026-09-30
+📌 Use DELETE /api/v2/resource/{id} instead
+📚 Migration guide: see MIGRATION_GUIDE.md
+```
+
+---
+
+## Breaking Changes Summary
+
+| Change | Impact | Migration | Deadline |
+|--------|--------|-----------|----------|
+| `legacy_field` removed | High | Remove from request | 2026-07-15 |
+| `status` values changed | Medium | Update enum parsing | 2026-08-15 |
+| v1 endpoints deprecated | High | Switch to v2 | 2026-09-30 |
+
+---
+
+## Test Contract Updates
+
+### New Tests Required
+
+```javascript
+describe('New Endpoints', () => {
+  it('GET /api/v1/resource with pagination', () => {
+    // Test new endpoint
+  })
+})
+
+describe('Modified Endpoints', () => {
+  it('POST /api/v1/resource with new_field', () => {
+    // Test modified endpoint with new field
+  })
+
+  it('POST /api/v1/resource rejects requests without new_field', () => {
+    // Test validation
+  })
+})
+
+describe('Deprecated Endpoints', () => {
+  it('DELETE /api/v1/resource/{id} shows deprecation warning', () => {
+    // Test deprecation notice in response headers
+  })
+})
+```
+
+### Tests to Remove/Update
+
+- [ ] Remove tests for `legacy_field`
+- [ ] Update status enum tests
+- [ ] Mark v1 deletion tests as deprecated
+
+---
+
+## Documentation Updates
+
+- [ ] README.md - API section updated
+- [ ] API_CONTRACTS.md - all endpoints documented
+- [ ] MIGRATION_GUIDE.md - created (if breaking changes)
+- [ ] CHANGELOG.md - entry added
+- [ ] Examples - all code samples updated
+
+---
+
+## Migration Guide (if applicable)
+
+### For Clients Using Removed Fields
+
+**OLD CODE:**
+```javascript
+const result = await api.post('/api/v1/resource', {
+  name: 'Test',
+  legacy_field: 'value'
+})
+```
+
+**NEW CODE:**
+```javascript
+const result = await api.post('/api/v1/resource', {
+  name: 'Test',
+  new_field: 'value'  // Required
+  // legacy_field: removed
+})
+```
+
+### Backward Compatibility (v1 to v2)
+
+**Timeline:**
+- 2026-06-01: v2 available, v1 still active
+- 2026-07-15: All clients should migrate
+- 2026-08-15: v1 marked for deletion
+- 2026-09-30: v1 endpoints removed
+
+**Check:**
+```bash
+# See which endpoints are in use
+curl -H "Authorization: Bearer TOKEN" \
+  https://api.example.com/admin/usage/v1-endpoints
+```
+
+---
+
+## Acceptance Checklist
+
+### Code Changes
+- [ ] Implementation matches contract
+- [ ] Request validation matches schema
+- [ ] Response format matches schema
+- [ ] All error codes returned
+- [ ] Auth checks implemented
+
+### Testing
+- [ ] New endpoint tests pass
+- [ ] Modified endpoint tests pass
+- [ ] Deprecated endpoint tests pass
+- [ ] Error handling tests pass
+- [ ] Integration tests pass
+- [ ] Coverage ≥ 80%
+
+### Documentation
+- [ ] API_CONTRACTS.md updated
+- [ ] Examples match new contract
+- [ ] Migration guide created
+- [ ] CHANGELOG entry added
+- [ ] Deprecation notices added
+
+### Deployment
+- [ ] Code review approved
+- [ ] All tests passing
+- [ ] Documentation verified
+- [ ] Ready for release
+
+---
+
+**Status**: ☐ Complete / ☐ In Progress / ☐ Blocked  
+**Blocker**: _if applicable_  
+**Owner**: _Name_  
+**Reviewed By**: _Name_

package/.codex/skills/genesis-architecture/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: architecture-skill
+description: Guide Codex through architecture analysis, boundary decisions, dependency direction, module ownership, and architecture documentation. Use before structural changes, new subsystems, cross-module work, or when architecture memory must be updated.
+---
+
+# Architecture Skill
+
+## Purpose
+Maintain architecture as a verifiable contract between modules, tests, docs, and repository memory.
+
+## When to use
+Use before subsystem changes, dependency changes, major refactors, new services, or architecture decisions.
+
+## When NOT to use
+Do not use for copy-only edits or isolated single-file fixes with no boundary impact.
+
+## Inputs required
+Read `.codebase/CURRENT_STATE.md`, `.codebase/MODULE_INDEX.md`, `.codebase/TEST_MATRIX.md`, then inspect relevant architecture files only.
+
+## Outputs required
+Architecture decision, impacted modules, dependency changes, diagrams when useful, and `.codebase/ARCHITECTURE.md` updates.
+
+## Required tests
+Add or update tests proving module boundaries and dependency behavior.
+
+## Required fixtures
+Create fixtures for new boundary inputs, outputs, and failure modes.
+
+## Required contract updates
+Update contracts when public behavior or module interfaces change.
+
+## Required codebase map updates
+Update `ARCHITECTURE.md`, `MODULE_INDEX.md`, and `DEPENDENCY_GRAPH.md`.
+
+## Token saving rules
+Read maps first, then only modules named by the maps. Prefer diagrams and checklists over repeated prose.
+
+## Acceptance criteria
+Boundaries are explicit, tests pass, contracts match implementation, and memory is current.
+
+## Common mistakes
+Changing dependency direction silently, documenting intent without tests, and scanning the whole repo before reading memory.
+
+## Recovery workflow
+If architecture drift is found, stop feature work, create a failing boundary test, update the contract, then repair the smallest module slice.
+

package/.codex/skills/genesis-architecture/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Architecture Skill"
+  short_description: "Plan and verify architecture boundaries"
+  default_prompt: "Use $architecture-skill to evaluate architecture impact and update repository memory."
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/genesis-architecture/checklists/checklist.md

@@ -0,0 +1,8 @@
+# Architecture Checklist
+
+- [ ] Read current state, module index, and test matrix.
+- [ ] Identify boundary impacted.
+- [ ] Add failing boundary test.
+- [ ] Update contracts.
+- [ ] Update `.codebase` memory.
+

package/.codex/skills/genesis-architecture/examples/example.md

@@ -0,0 +1,4 @@
+# Example
+
+Use before splitting a provider module into separate API and persistence boundaries.
+

package/.codex/skills/genesis-architecture/templates/architecture-decision-template.md

@@ -0,0 +1,14 @@
+# Architecture Decision Template
+
+## Decision
+
+## Context
+
+## Constraints
+
+## Contracts Changed
+
+## Tests Added
+
+## Memory Updates
+

package/.codex/skills/genesis-codebase-map/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: codebase-map-skill
+description: Maintain repository memory and compressed codebase maps for token-efficient Codex operation. Use when files move, modules change, contracts change, tests change, or repository summaries need updating.
+---
+
+# Codebase Map Skill
+
+## Purpose
+Keep `.codebase/` accurate so future agents read summaries before source.
+
+## When to use
+Use after meaningful code, contract, test, route, provider, pipeline, or architecture changes.
+
+## When NOT to use
+Do not use for changes that do not affect repository understanding.
+
+## Inputs required
+Changed files, verification results, contracts touched, and current `.codebase` files.
+
+## Outputs required
+Updated module index, current state, test matrix, dependency graph, and context summaries.
+
+## Required tests
+Run `scripts/verify.sh` after memory updates.
+
+## Required fixtures
+Update fixture index when fixtures change.
+
+## Required contract updates
+Reflect changed contracts in `.codebase/API_CONTRACTS.md`.
+
+## Required codebase map updates
+Update all impacted `.codebase` files.
+
+## Token saving rules
+Summaries must be short, link to source locations, and avoid duplicating full manuals.
+
+## Acceptance criteria
+Future agents can orient by reading `CURRENT_STATE.md`, `MODULE_INDEX.md`, and `TEST_MATRIX.md`.
+
+## Common mistakes
+Letting memory drift, overloading summaries with full docs, and forgetting test matrix changes.
+
+## Recovery workflow
+If memory conflicts with code, trust verified code, update memory, and add a known problem entry.
+

package/.codex/skills/genesis-codebase-map/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Codebase Map Skill"
+  short_description: "Maintain compressed repository memory"
+  default_prompt: "Use $codebase-map-skill to update repository memory after this change."
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/genesis-codebase-map/checklists/checklist.md

@@ -0,0 +1,7 @@
+# Codebase Map Checklist
+
+- [ ] Current state updated.
+- [ ] Module index updated.
+- [ ] Test matrix updated.
+- [ ] Context summaries still concise.
+

package/.codex/skills/genesis-codebase-map/examples/example.md

@@ -0,0 +1,4 @@
+# Example
+
+After adding a new contract test folder, update `TEST_MATRIX.md` and `MODULE_INDEX.md`.
+

package/.codex/skills/genesis-codebase-map/templates/map-update-template.md

@@ -0,0 +1,8 @@
+# Codebase Map Update
+
+## Changed Files
+## Impacted Modules
+## Tests
+## Contracts
+## Memory Files Updated
+