codex-genesis-harness 0.1.6 → 0.1.7

package/.codebase/CURRENT_STATE.md

@@ -1,10 +1,11 @@
 # Current State: COMPLETED
-Last updated: Mon Jun 01 10:30:00 +07 2026
+Last updated: Mon Jun 01 17:15:00 +07 2026
 
 ## Reason
-Completed the comprehensive refactoring and bilingual polish of the release documentation (`README.md`, `README.EN.md`, `README.VI.md`) for the `0.1.6` release.
-- Highlighted the **Harness Architecture** core pillars and subsystems (Context Compaction, Tool Call Offloading, Self-Healing Verify-Fix Loops, 5-Phase MVP Roadmap, and Zero-Drift Gates).
-- Presented a crisp **Standard Agent vs. Harness** comparison table to clearly explain its architectural advantages.
-- Cleaned up duplicate installation segments and standardized all skill catalogs on 25 skills, including registering the missing `genesis-mvp-planning` skill in the Vietnamese documentation table.
-- Verified all structural, installation, and packaging pipelines successfully (`npm run verify && npm run eval && npm run pack:check` all pass 100% cleanly).
-
+Successfully completed the Visual Mockup Generation & Interactive TUI Mockup Viewer integration (v0.3.0), followed by Harness Engineering standardizations and preparation for release `0.1.7`:
+- **Interactive Keyboard-Navigated CLI TUI**: Developed an elegant console interface for `genesis-harness view-mockup` capturing stdin keypresses.
+- **Harness Verification Streamlining**: Refactored `scripts/verify.sh` and `scripts/run-evals.sh` to dynamically evaluate skill names, removing legacy hard-coded mapping logic. Cleaned up deprecated skills (e.g., `genesis-mvp-planning`, `genesis-release-orchestration`, `genesis-state-machine`, `genesis-research`, `genesis-docs`).
+- **Skill Consolidation**: Merged overlapping skills to resolve duplicated slash commands and clean up the architecture.
+- **Bead Memory Test Coverage**: Added rigorous CLI command validations in `scripts/run-evals.sh` to guarantee that `remember`, `recall`, `prime`, and `forget` function reliably.
+- **Skill Enrichment Directives**: Packaged new visual contract requirements inside `genesis-design-spec` (utilizing `generate_image`) and visual alignment checks inside `genesis-new-design` (utilizing `view_file`).
+- **Verification Evidence**: Structural checks and regression evaluations pass 100% cleanly, confirming absolute stability in the current codebase state. Ready for 0.1.7 release.

package/.codebase/RECOVERY_POINTS.md

@@ -1,8 +1,8 @@
 # Recovery Points
 
-**Purpose**: Document where implementation can be paused and resumed without losing context or creating inconsistencies.
+**Purpose**: Document where harness architecture 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.
+**Use When**: Evolution of the Codex harness (verification loops, CLI tools, scripts) needs to be paused, or when a rollback is necessary due to environment breakage.
 
 ---
 
@@ -10,429 +10,74 @@
 
 | 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_ |
+| TUI Mockup Viewer Integration | ✓ Complete | `.codebase/CURRENT_STATE.md` | 2026-06-01 |
+| Harness Verification Streamlining | ✓ Complete | `.codebase/CURRENT_STATE.md` | 2026-06-01 |
+| Bead Memory Regression Tests | ✓ Complete | `scripts/run-evals.sh` | 2026-06-01 |
+| Harness Engineering Overhaul | ⏸️ Idle (Stable) | `scripts/verify.sh` | 2026-06-01 |
 
 ---
 
-## Phase: Planning
+## Phase: Harness Verification Streamlining & Memory Evals
 
 **Status**: ✓ Complete  
-**Start Date**: _date_  
-**End Date**: _date_  
-**Resumption**: Not needed
+**Last Updated**: 2026-06-01  
 
 ### What Happened
 
-All requirements gathered, validated, and documented.
+- Cleaned up legacy/deprecated skills (e.g., `genesis-mvp-planning`, `genesis-release-orchestration`) from `scripts/verify.sh`, `scripts/uninstall.sh`, and `scripts/run-evals.sh`.
+- Removed hard-coded skill name mappings (`expected_name` switch statements), enabling dynamic mapping directly based on directory names.
+- Added test coverage in `run-evals.sh` for the local bead memory commands (`remember`, `recall`, `prime`, `forget`).
+- Enforced `state-machine.md` presence in `verify_harness_skill()`.
 
-### 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:**
+### Safe State Confirmation
 
+The harness currently passes all structural tests cleanly.
 ```bash
-# 1. Commit current progress
-git add -A
-git commit -m "feat: OAuth provider implementation (50% complete)"
+# Verify structure
+./scripts/verify.sh
 
-# 2. Verify tests pass
-npm test
+# Verify regression
+./scripts/run-evals.sh
 
-# 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
+# Dry-run package integrity
+npm run pack:check
 ```
 
 ---
 
 ## Rollback Points
 
-### If Implementation Gets Stuck
+### If A Future Harness Evolution Breaks the CLI/Environment
 
-**Rollback Level 1: Last Commit**
+**Rollback Level 1: Last Stable Run (Current State)**
+If a new change to `bin/genesis-harness.js` or `scripts/verify.sh` creates infinite loops or immediate failures:
 ```bash
-git reset --hard HEAD
+git checkout -- bin/genesis-harness.js scripts/verify.sh scripts/run-evals.sh
 npm install
-npm test  # Should pass
+./scripts/verify.sh
 ```
 
-**Rollback Level 2: Before This Feature**
+**Rollback Level 2: Full Repository Reset**
+If tests are failing in a manner that contaminates local fixtures or memory:
 ```bash
-git checkout main
+git reset --hard HEAD
+git clean -fd
 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
+./scripts/verify.sh
 ```
 
 ---
 
-## 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
+## Checklist: Before Pausing Work on Harness Evolutions
 
-- [ ] 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 |
+- [ ] `scripts/verify.sh` passing cleanly (Exit Code 0)
+- [ ] `scripts/run-evals.sh` passing cleanly (Exit Code 0)
+- [ ] Script files verified for POSIX/LF line endings
+- [ ] No uncommitted changes in core scripts that break existing workflows
+- [ ] `.codebase/CURRENT_STATE.md` updated with exact phase details
 
 ---
 
 ## 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_
+**Owner**: Codex Harness Engineering Team
+**Last Validated**: 2026-06-01

package/.codebase/beads.json

@@ -0,0 +1,16 @@
+[
+  {
+    "id": "212329",
+    "category": "general",
+    "fact": "Always use PORT 8080 when running development servers locally.",
+    "timestamp": "2026-06-01T07:22:12.428Z",
+    "git_commit": "92d8138"
+  },
+  {
+    "id": "25d72a",
+    "category": "api",
+    "fact": "Verify request.json schema before running visual regression tests.",
+    "timestamp": "2026-06-01T07:22:33.273Z",
+    "git_commit": "92d8138"
+  }
+]

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

@@ -1,5 +1,5 @@
 ---
-name: ai-provider-skill
+name: genesis-ai-provider
 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.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-name: api-contract-skill
+name: genesis-api-contract
 description: Create and verify API contracts before endpoint implementation. Use for API routes, service interfaces, validation rules, error shapes, snapshots, and endpoint tests.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-name: api-sync-skill
+name: genesis-api-sync
 description: Automatic API contract synchronization. Detects API changes in implementation, updates API_CONTRACTS.md, regenerates test contracts, and maintains backward compatibility documentation. Use after API-related implementation or when contracts drift from actual code.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-name: architecture-skill
+name: genesis-architecture
 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.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-name: codebase-map-skill
+name: genesis-codebase-map
 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.
 ---
 

package/.codex/skills/genesis-debug-guide/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: debug-guide-skill
+name: genesis-debug-guide
 description: "Systematic debugging for test failures, runtime errors, and production bugs. Follows TDD debugging patterns, isolation strategies, and observability-driven root cause analysis. Auto-triggers after bug fixes to verify fix quality and prevent regressions."
 ---
 

package/.codex/skills/genesis-design-spec/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: design-spec-skill
+name: genesis-design-spec
 description: Define UI design specs, route contracts, visual states, accessibility expectations, and UI/API synchronization before frontend implementation. Use for new screens, redesigns, visual QA, or UI contract updates.
 ---
 
@@ -18,7 +18,7 @@ Do not use for backend-only changes with no UI effect.
 UI route, audience, state list, API dependencies, fixtures, and visual references if available.
 
 ## Outputs required
-UI contract, Playwright fixture, acceptance states, and visual regression expectations.
+UI contract, a generated visual mockup image representing the screen layout (saved as `mockup.png` in the active feature/bug directory), Playwright fixture, acceptance states, and visual regression expectations.
 
 ## Required tests
 Create load, interaction, validation, API sync, and visual regression tests where applicable.
@@ -36,7 +36,7 @@ Update `.codebase/UI_ROUTES.md` and frontend summary.
 Use state tables and route maps instead of long visual prose.
 
 ## Acceptance criteria
-The UI can be implemented and tested without guessing states or API behavior.
+The UI can be implemented and tested without guessing states or API behavior. A high-fidelity visual mockup `mockup.png` must be created using the `generate_image` tool and saved in the active task directory as the visual contract.
 
 ## Common mistakes
 Designing only the happy path, skipping empty/error states, and omitting API synchronization.

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

@@ -19,7 +19,7 @@ Use for project initialization, planning, feature work, bug fixes, audits, revie
 Do not use for simple read-only answers that do not require repository workflow or durable artifacts.
 
 ## Inputs required
-Read `.codebase/state.json` (MANDATORY on boot), `.codebase/CURRENT_STATE.md`, `.codebase/MODULE_INDEX.md`, and `.codebase/TEST_MATRIX.md` when present, then inspect only relevant files.
+Run `genesis-harness status` and `genesis-harness docs` (or `genesis-harness prime`) IMMEDIATELY on boot to retrieve a high-fidelity, token-minimized FSM state, active roadmap checklist, memory beads, and API contract catalog. Do NOT manually run search commands or read entire planning folders to discover the repository state. Only inspect specific relevant code files.
 
 ## Outputs required
 Plan or implementation artifact, tests, fixtures, verification evidence, docs sync, and codebase memory updates.
@@ -37,7 +37,7 @@ Update API, agent, event, or UI contracts when public behavior changes.
 Update `.codebase` memory after meaningful changes.
 
 ## Token saving rules
-Read summaries before source files, maps before modules, and avoid loading the entire repository.
+Always prioritize running standard CLI queries (`genesis-harness status`, `docs`, `recall`, and `prime`) to pull structured data rather than traversing directories manually. Read summaries before source files, maps before modules, and avoid loading the entire repository.
 
 ## Acceptance criteria
 Work is complete only when tests pass, contracts and docs are current, and verification evidence is reported.
@@ -170,6 +170,7 @@ Bundled references live under `references/`. Load them only when needed:
 - `references/planning-schema.md`: detailed `.planning/` file meanings and required subtrees.
 - `references/research-rubric.md`: local/external evidence format for research.
 - `references/quality-rubric.md`: scoring rubric for `QUALITY_SCORE.md`.
+- `references/state-machine.md`: FSM state definitions, transitions, and verification gates.
 
 Bundled scripts live under `scripts/`. Prefer copying or adapting these into `.planning/scripts/` or project scripts during `/init`:
 

package/.codex/skills/genesis-harness-engineering/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: harness-engineering-skill
+name: genesis-harness-engineering
 description: "Evolve the Codex harness itself: verification loops, repository memory, test-first scaffolds, resumability, observability, and autonomous workflow reliability. Use for changes to this repository's skill system or harness architecture."
 ---
 

package/.codex/skills/genesis-new-design/SKILL.md

@@ -17,7 +17,7 @@ Use when building a new web page, app screen, dashboard, tool, landing page, or
 Do not use for redesigning existing UI without first preserving behavior; use `genesis-upgrade-design` instead.
 
 ## Inputs required
-Product intent, target users, primary workflow, stack details, route or entry point, state list, and visual constraints.
+Product intent, target users, primary workflow, stack details, route or entry point, state list, visual constraints, and the generated visual contract image `mockup.png` (which MUST be loaded via the `view_file` tool to inspect layouts, color choices, and dimensions before coding).
 
 ## Outputs required
 Implemented UI, UI contract, fixtures, responsive states, visual verification, and docs or memory updates.
@@ -55,6 +55,7 @@ If visual output fails, capture screenshot evidence, update the fixture or contr
 
 2. Define the design intent from the request:
    - Identify audience, product category, primary task, density, tone, and constraints.
+   - Proactively inspect `mockup.png` using the `view_file` tool to absorb the visual direction, color system, and placement details.
    - Choose one clear visual direction and commit to it across typography, color, spacing, surfaces, iconography, and motion.
    - For tools, dashboards, and operational apps, prioritize scanning, repeated use, compact controls, and predictable navigation over decorative hero layouts.
 

package/.codex/skills/genesis-pipeline-orchestration/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pipeline-orchestration-skill
+name: genesis-pipeline-orchestration
 description: Run end-to-end Codex harness orchestration phases from repository analysis through tests, fixtures, implementation, contracts, memory, docs, and change summaries. Use for autonomous multi-phase work.
 ---