codex-genesis-harness 0.1.0 → 0.1.4

package/fixtures/render/render-fixture-template.md

@@ -0,0 +1,14 @@
+# Render Fixture Template
+
+## Input
+
+Describe media inputs, timeline, subtitles, voice assets, and image assets.
+
+## Expected Output
+
+Describe rendered artifact metadata, duration, dimensions, and validation checks.
+
+## Validation Notes
+
+Check missing assets, invalid media, and deterministic output metadata.
+

package/fixtures/tts/tts-fixture-template.md

@@ -0,0 +1,14 @@
+# TTS Fixture Template
+
+## Input
+
+Text, voice, language, timing, and provider options.
+
+## Expected Output
+
+Audio metadata, transcript alignment, and provider response shape.
+
+## Validation Notes
+
+Check retries, provider errors, empty text, and persistence.
+

package/fixtures/videos/video-fixture-template.md

@@ -0,0 +1,14 @@
+# Video Fixture Template
+
+## Input
+
+Scene plan, audio, subtitles, images, transitions, and render options.
+
+## Expected Output
+
+Video artifact metadata, duration, and validation checks.
+
+## Validation Notes
+
+Check missing clips, bad timing, retry behavior, and resumability.
+

package/observability/agent-runs/agent-run-template.md

@@ -0,0 +1,22 @@
+# Agent Run Template
+
+## Reason
+
+Why the autonomous change was started.
+
+## Predicted Impact
+
+Expected files, behavior, and risks.
+
+## Files Changed
+
+List changed files.
+
+## Tests Executed
+
+List commands and results.
+
+## Result
+
+Completed, blocked, or reverted.
+

package/observability/decision-logs/decision-log-template.md

@@ -0,0 +1,18 @@
+# Decision Log Template
+
+## Decision
+
+What changed.
+
+## Reason
+
+Why this path was chosen.
+
+## Rejected Options
+
+Alternatives and reasons.
+
+## Verification
+
+Evidence collected.
+

package/observability/failures/failure-template.md

@@ -0,0 +1,18 @@
+# Failure Template
+
+## Failure
+
+What failed and where.
+
+## Root Cause
+
+What caused it.
+
+## Recovery
+
+Steps taken or required.
+
+## Prevention
+
+Test, contract, or checklist to prevent recurrence.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-genesis-harness",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Install and manage the Project Genesis Harness Codex skill.",
   "license": "MIT",
   "bin": {
@@ -14,7 +14,13 @@
   },
   "files": [
     ".codex-plugin",
-    ".codex/skills/project-genesis-harness",
+    ".codex/skills",
+    ".codebase",
+    "contracts",
+    "fixtures",
+    "tests",
+    "playwright",
+    "observability",
     "bin",
     "scripts",
     "README.md",

package/playwright/e2e/e2e-template.md

@@ -0,0 +1,4 @@
+# Playwright E2E Template
+
+For every critical screen: load route, perform primary workflow, assert final UI state, assert API synchronization, and capture trace on failure.
+

package/playwright/fixtures/ui-fixture-template.md

@@ -0,0 +1,4 @@
+# UI Fixture Template
+
+Define route, mocked API responses, user role, viewport, expected text, and expected visual states.
+

package/playwright/smoke/smoke-template.md

@@ -0,0 +1,4 @@
+# Playwright Smoke Template
+
+For every screen: route loads, core landmark exists, primary action is reachable, and no console errors appear.
+

package/playwright/visual/visual-regression-template.md

@@ -0,0 +1,4 @@
+# Visual Regression Template
+
+Capture desktop and mobile screenshots for default, loading, empty, error, and success states when available.
+

package/scripts/README.md

@@ -0,0 +1,342 @@
+# Scripts Reference
+
+Utility scripts for verifying, testing, and managing the Genesis Harness project.
+
+## Quick Start
+
+```bash
+# First time setup
+./scripts/install.sh
+
+# Verify everything works
+./scripts/verify.sh
+
+# Before PR submission
+npm run verify && npm run eval && npm run pack:check
+```
+
+## Scripts
+
+### install.sh
+
+**Purpose**: Install Genesis Harness skills and dependencies
+
+**When to run**:
+- First time setting up the project
+- After cloning the repository
+- When adding new skills
+
+**What it does**:
+- Copies skills to `~/.codex/skills/`
+- Installs npm dependencies
+- Sets up environment paths
+- Validates installation
+
+**Usage**:
+```bash
+# Default installation
+./scripts/install.sh
+
+# Custom homes
+CODEX_HOME=/path/to/.codex ./scripts/install.sh
+GENESIS_HARNESS_HOME=/path/to/.agents ./scripts/install.sh
+
+# Skip postinstall
+GENESIS_HARNESS_SKIP_POSTINSTALL=1 npm install -g codex-genesis-harness@latest
+```
+
+**Success indicator**: "Installation complete" message, no errors
+
+---
+
+### verify.sh
+
+**Purpose**: Run all verification checks
+
+**When to run**:
+- After making code changes
+- Before submitting a PR (REQUIRED)
+- When debugging test failures
+- During development cycles
+
+**What it does**:
+- Runs all unit tests
+- Runs all integration tests
+- Checks TypeScript compilation
+- Validates contract schemas
+- Checks for linting errors
+- Verifies package integrity
+
+**Usage**:
+```bash
+# Verify project root
+./scripts/verify.sh
+
+# Verify installed copy
+./scripts/verify.sh ~/.codex/skills
+
+# Run specific test type
+npm run verify:unit
+npm run verify:integration
+npm run verify:e2e
+```
+
+**Success indicator**: "✓ All checks passed", exit code 0
+
+**Common issues**:
+- Test failures → Fix code, re-run
+- Schema validation errors → Update contracts
+- TypeScript errors → Fix type issues
+
+---
+
+### run-evals.sh
+
+**Purpose**: Run evaluation suite for coverage and quality metrics
+
+**When to run**:
+- Before final PR submission
+- During sprint reviews
+- When verifying coverage meets 80%
+- Performance benchmarking
+
+**What it does**:
+- Measures test coverage (target: 80%+)
+- Runs performance benchmarks
+- Checks code complexity
+- Validates fixture integrity
+- Generates coverage reports
+
+**Usage**:
+```bash
+# Run full evaluation
+./scripts/run-evals.sh
+
+# Run specific evaluation
+npm run eval:coverage
+npm run eval:performance
+npm run eval:complexity
+```
+
+**Output**: Coverage report, performance metrics, complexity analysis
+
+**Success indicator**: Coverage 80%+, no performance regressions
+
+---
+
+### npm Commands
+
+These are defined in `package.json` and run via npm.
+
+#### npm run verify
+
+**Alias**: `./scripts/verify.sh`
+
+Runs all verification checks. **Use this before every PR.**
+
+```bash
+npm run verify
+```
+
+---
+
+#### npm run eval
+
+**Alias**: `./scripts/run-evals.sh`
+
+Runs evaluation suite. Check coverage and quality metrics.
+
+```bash
+npm run eval
+```
+
+---
+
+#### npm run pack:check
+
+**Purpose**: Verify package will publish correctly
+
+**When to run**:
+- Before publishing to npm
+- Before PR submission
+- When package.json changes
+
+**What it does**:
+- Simulates npm publish
+- Validates all files in package
+- Checks naming and metadata
+- Verifies no secrets exposed
+
+**Usage**:
+```bash
+npm run pack:check
+```
+
+**Success indicator**: "✓ Package ready for publish", exit code 0
+
+---
+
+## Typical Development Workflow
+
+### 1. Start a Feature
+
+```bash
+./scripts/install.sh              # If first time
+./scripts/verify.sh               # Baseline check
+```
+
+### 2. Make Changes
+
+Write code, tests, update contracts.
+
+### 3. Verify Locally
+
+```bash
+./scripts/verify.sh               # All tests pass
+npm run eval                      # Coverage 80%+
+```
+
+### 4. Before PR
+
+```bash
+./scripts/verify.sh               # Final verification
+npm run eval                      # Final coverage check
+npm run pack:check                # Package integrity
+```
+
+### 5. After Merge
+
+```bash
+./scripts/install.sh              # Re-install with new code
+./scripts/verify.sh               # Validate in production paths
+```
+
+---
+
+## Debugging Failed Scripts
+
+### Verify Script Fails
+
+**Check test output**:
+```bash
+npm test 2>&1 | tail -50         # Last 50 lines of output
+```
+
+**Run single test**:
+```bash
+npm run test -- --testNamePattern="specific test"
+```
+
+**Run test file**:
+```bash
+npm run test tests/unit/my-feature.test.md
+```
+
+### Eval Script Fails
+
+**Check coverage only**:
+```bash
+npm run eval:coverage
+```
+
+**Check specific metric**:
+```bash
+npm run eval:performance
+```
+
+### Pack Check Fails
+
+**Check what's included**:
+```bash
+npm pack --dry-run | head -100
+```
+
+**Check for secrets**:
+```bash
+grep -r "API_KEY\|SECRET\|password" . --exclude-dir=node_modules
+```
+
+---
+
+## Environment Variables
+
+Control script behavior:
+
+```bash
+# Skip postinstall during npm install
+GENESIS_HARNESS_SKIP_POSTINSTALL=1
+
+# Custom skill installation paths
+CODEX_HOME=/path/to/.codex
+GENESIS_HARNESS_HOME=/path/to/.agents
+
+# Enable verbose output
+DEBUG=*
+
+# Set Node version
+NODE_VERSION=18.0.0
+```
+
+---
+
+## Manual Verification
+
+If scripts fail, verify manually:
+
+```bash
+# Check Node version
+node --version              # Should be 18+
+
+# Check npm modules installed
+npm ls                      # Should have no errors
+
+# List test files
+find tests -name "*.test.md" -type f
+
+# Count coverage
+find . -name "coverage" -type d
+```
+
+---
+
+## Performance Tips
+
+**Faster local development**:
+```bash
+# Skip e2e tests during development
+npm run verify:unit
+npm run verify:integration
+
+# Then run full verify before PR:
+npm run verify
+```
+
+**Cache improvements**:
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Reinstall
+./scripts/install.sh
+```
+
+---
+
+## Continuous Integration
+
+These scripts run in CI/CD:
+
+1. `npm install` - Install dependencies
+2. `npm run verify` - All checks must pass
+3. `npm run eval` - Coverage and quality metrics
+4. `npm run pack:check` - Package integrity
+
+**Failed CI blocks PR merge.** Fix locally before pushing.
+
+---
+
+## Support
+
+- Script errors? → Check exit code with `echo $?`
+- Still failing? → Read full output, not just errors
+- Clear cache and try again: `npm cache clean --force && ./scripts/install.sh`

package/scripts/compact-context.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Genesis Codex Harness — Context Compaction Engine
+# ==============================================================================
+# Summarizes active project planning files, active tasks, and logs into a single
+# .planning/CONTEXT_SUMMARY.md file to safely offload context before compacting.
+# Reduces context window usage and prevents Context Rot.
+# ==============================================================================
+
+set -euo pipefail
+
+PLANNING_DIR="${1:-.planning}"
+SUMMARY_FILE="$PLANNING_DIR/CONTEXT_SUMMARY.md"
+
+if [ ! -d "$PLANNING_DIR" ]; then
+  echo "Error: Planning directory '$PLANNING_DIR' does not exist." >&2
+  exit 1
+fi
+
+echo "==> Compacting active context..."
+
+{
+  echo "# Context Compaction Summary"
+  echo "Generated: $(date +'%Y-%m-%d %H:%M:%S')"
+  echo ""
+  echo "## 📊 Active State Summary"
+  if [ -f "$PLANNING_DIR/STATE.md" ]; then
+    grep -E "^- (Current Phase|Active Feature|Last Completed Task|Next Task|Blockers):" "$PLANNING_DIR/STATE.md" || true
+  else
+    echo "State file not found. Project initialized but state unpopulated."
+  fi
+  echo ""
+  echo "## 🎯 Key Architectural Invariants"
+  if [ -f "$PLANNING_DIR/ARCHITECTURE.md" ]; then
+    head -n 25 "$PLANNING_DIR/ARCHITECTURE.md"
+  else
+    echo "Architecture file not found."
+  fi
+  echo ""
+  echo "## 📝 Active Task Progress"
+  # Find all task lists in active features or bugs
+  find "$PLANNING_DIR/features" "$PLANNING_DIR/bugs" -name "TASKS.md" 2>/dev/null | while read -r task_file; do
+    echo "### Tasks for: $(basename "$(dirname "$task_file")")"
+    grep -E "^- \[[x~ ]\]" "$task_file" | tail -n 15 || true
+    echo ""
+  done
+  echo ""
+  echo "## ⚠️ Fragile Areas & Lessons Learned"
+  if [ -f "$PLANNING_DIR/PITFALLS.md" ]; then
+    head -n 15 "$PLANNING_DIR/PITFALLS.md"
+  fi
+} > "$SUMMARY_FILE"
+
+echo "==> Context compaction complete! Summary saved to: file://$(pwd)/$SUMMARY_FILE"

package/scripts/detect-changes.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+
+# detect-changes.sh
+# Auto-detect file changes and identify what .codebase docs need updating
+# Run after implementation to identify sync needs
+
+set -e
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CODEBASE_DIR="$PROJECT_ROOT/.codebase"
+
+# Color output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=== Auto-Detect Changes ===${NC}"
+echo ""
+
+# Track what needs updating
+UPDATES_NEEDED=()
+
+# 1. Check for new/modified API files
+echo -e "${YELLOW}Scanning API changes...${NC}"
+api_files=$(find "$PROJECT_ROOT/src" -name "*api*" -o -name "*endpoint*" -o -name "*route*" 2>/dev/null || true)
+if [ ! -z "$api_files" ]; then
+  echo "  ✓ API files detected"
+  UPDATES_NEEDED+=("API_CONTRACTS.md")
+fi
+
+# 2. Check for database/model changes
+echo -e "${YELLOW}Scanning database changes...${NC}"
+if find "$PROJECT_ROOT" -type f \( -name "*model*" -o -name "*schema*" -o -name "*db*" \) 2>/dev/null | grep -q .; then
+  echo "  ✓ Database/model files detected"
+  UPDATES_NEEDED+=("DOMAIN_MODELS.md")
+fi
+
+# 3. Check for route/UI changes
+echo -e "${YELLOW}Scanning UI route changes...${NC}"
+if find "$PROJECT_ROOT" -type f \( -name "*route*" -o -name "*page*" \) -path "*/src/pages/*" 2>/dev/null | grep -q .; then
+  echo "  ✓ UI route files detected"
+  UPDATES_NEEDED+=("UI_ROUTES.md")
+fi
+
+# 4. Check for test changes
+echo -e "${YELLOW}Scanning test changes...${NC}"
+test_count=$(find "$PROJECT_ROOT/tests" -name "*.test.*" 2>/dev/null | wc -l)
+if [ "$test_count" -gt 0 ]; then
+  echo "  ✓ $test_count test files found"
+  UPDATES_NEEDED+=("TEST_MATRIX.md")
+fi
+
+# 5. Check for module changes
+echo -e "${YELLOW}Scanning module exports...${NC}"
+if find "$PROJECT_ROOT/src" -name "index.*" 2>/dev/null | grep -q .; then
+  echo "  ✓ Module index files detected"
+  UPDATES_NEEDED+=("MODULE_INDEX.md")
+fi
+
+# 6. Check for dependency changes
+echo -e "${YELLOW}Scanning dependency changes...${NC}"
+if [ -f "$PROJECT_ROOT/package.json" ]; then
+  echo "  ✓ package.json found"
+  UPDATES_NEEDED+=("DEPENDENCY_GRAPH.md")
+fi
+
+# 7. Check for architecture changes
+echo -e "${YELLOW}Scanning architecture changes...${NC}"
+if find "$PROJECT_ROOT" -name "*.md" -exec grep -l "architecture\|diagram\|flow" {} \; 2>/dev/null | grep -q .; then
+  echo "  ✓ Architecture documentation found"
+  UPDATES_NEEDED+=("ARCHITECTURE.md")
+fi
+
+# 8. Always update CURRENT_STATE after any implementation
+UPDATES_NEEDED+=("CURRENT_STATE.md")
+
+# Remove duplicates
+UPDATES_NEEDED=($(printf '%s\n' "${UPDATES_NEEDED[@]}" | sort -u))
+
+echo ""
+echo -e "${GREEN}Files that need updating:${NC}"
+for file in "${UPDATES_NEEDED[@]}"; do
+  echo "  → $CODEBASE_DIR/$file"
+done
+
+echo ""
+echo -e "${BLUE}=== Update Summary ===${NC}"
+echo "Run these commands to sync documentation:"
+echo ""
+
+for file in "${UPDATES_NEEDED[@]}"; do
+  case $file in
+    "API_CONTRACTS.md")
+      echo -e "${YELLOW}1. API_CONTRACTS.md${NC}"
+      echo "   Check: src/**/api.ts, src/**/endpoint.ts"
+      echo "   Run: extract-api-contracts.sh"
+      echo ""
+      ;;
+    "DOMAIN_MODELS.md")
+      echo -e "${YELLOW}2. DOMAIN_MODELS.md${NC}"
+      echo "   Check: src/**/models, src/**/schema"
+      echo "   Run: extract-domain-models.sh"
+      echo ""
+      ;;
+    "UI_ROUTES.md")
+      echo -e "${YELLOW}3. UI_ROUTES.md${NC}"
+      echo "   Check: src/pages/**, src/**/route.ts"
+      echo "   Run: extract-routes.sh"
+      echo ""
+      ;;
+    "TEST_MATRIX.md")
+      echo -e "${YELLOW}4. TEST_MATRIX.md${NC}"
+      echo "   Check: tests/** coverage"
+      echo "   Run: npm test -- --coverage && update-test-matrix.sh"
+      echo ""
+      ;;
+    "MODULE_INDEX.md")
+      echo -e "${YELLOW}5. MODULE_INDEX.md${NC}"
+      echo "   Check: src/**/index.ts exports"
+      echo "   Run: extract-modules.sh"
+      echo ""
+      ;;
+    "DEPENDENCY_GRAPH.md")
+      echo -e "${YELLOW}6. DEPENDENCY_GRAPH.md${NC}"
+      echo "   Check: package.json dependencies"
+      echo "   Run: extract-dependencies.sh"
+      echo ""
+      ;;
+    "ARCHITECTURE.md")
+      echo -e "${YELLOW}7. ARCHITECTURE.md${NC}"
+      echo "   Check: System design and data flows"
+      echo "   Run: Review and update manually"
+      echo ""
+      ;;
+    "CURRENT_STATE.md")
+      echo -e "${YELLOW}8. CURRENT_STATE.md${NC}"
+      echo "   Always update after changes"
+      echo "   Run: update-state.sh"
+      echo ""
+      ;;
+  esac
+done
+
+echo -e "${BLUE}Next steps:${NC}"
+echo "1. Update each file using the commands above"
+echo "2. Run: ./scripts/verify.sh"
+echo "3. Commit changes with descriptive message"
+echo "4. Create PR with documentation sync"
+echo ""