codex-genesis-harness 0.1.6 → 0.1.8

package/.codebase/memories/lessons_learned.md

@@ -0,0 +1,21 @@
+# Lessons Learned & Historical Bugs
+
+This file chronicles the major failures, recursive bugs, and architectural dead-ends we have encountered. It acts as an immune system preventing the agent from repeating history.
+
+## 1. Duplicate Slash Commands in Registry
+- **Symptom**: Agent registered 4 copies of the same slash command for a single skill.
+- **Root Cause**: The CLI script recursively scanned the entire `.codex/` directory for active skills, accidentally parsing backup folders (`.codex/backup/`) generated during skill upgrades.
+- **Resolution**: Backup directories must ALWAYS be placed completely outside the active parsed directory (e.g., moved to `~/.codex/backups` globally).
+- **Rule**: When doing file tree walks for plugins/skills, always explicitly ignore `.git`, `node_modules`, `backup`, and `tmp` folders.
+
+## 2. Documentation Drift & Broken Contracts
+- **Symptom**: Code in `scripts/` changed logic without updating `contracts/`.
+- **Root Cause**: Agent skipped the documentation step after a "quick fix" code edit.
+- **Resolution**: Implemented Validation Gates (`npm run verify`).
+- **Rule**: Never finalize a code edit without explicitly checking `TEST_MATRIX.md` and related schemas in `contracts/`. The validation gate will fail the build if it detects drift.
+
+## 3. Excessive Token Usage from `cat` and `ls`
+- **Symptom**: Context window flooded with massive minified bundle files or deep directory trees.
+- **Root Cause**: Using `cat` on large files or `ls -R` without filters.
+- **Resolution**: 
+- **Rule**: Always use the native `view_file`, `list_dir`, and `grep_search` tools with precise line bounds or search terms. NEVER `cat` a file directly in bash if a native agent tool exists.

package/.codebase/memories/preferences.md

@@ -0,0 +1,17 @@
+# Developer Preferences
+
+This file records the specific technical choices, preferences, and stylistic guidelines of the human developer for this repository. Adhere to these implicitly during code generation and problem-solving.
+
+## Technology Stack
+- **Primary Language**: JavaScript (Node.js for backend scripts). Keep code modern but compatible with Node >= 18.
+- **Testing**: Use standard Unix bash testing scripts (`verify.sh`, `run-evals.sh`) and standard Node asserts for unit testing unless specified otherwise.
+- **Frontend/UI**: When dealing with UI generation, prefer Vanilla CSS for precise control and maximum performance. Emphasize "WOW" factor, modern gradients, glassmorphism, and responsive layouts.
+
+## Architectural Choices
+- **Harness Engineering**: The system relies on state machines (FSM) and validation gates. Never skip a validation gate (`contract_integrity_gate.js`, `healing_telemetry.js`).
+- **File Integrity**: Ensure all metadata inside `.codebase/` and `contracts/` stays perfectly synchronized with any changes to actual codebase logic (`scripts/spec_visual_sync.js`).
+
+## Communication Style
+- Be concise, professional, and skip unnecessary pleasantries when delivering technical solutions.
+- Use GitHub Flavored Markdown for formatting logs, alerts, and instructions.
+- Provide Vietnamese localization in READMEs and user-facing artifacts where possible, as the user frequently requests Vietnamese communication.

package/.codebase/state.json

@@ -1,37 +1,58 @@
 {
   "current_state": "COMPLETED",
+  "completed_at": "2026-06-03T02:42:00Z",
+  "active_work": "Full Score Harness Fix — L02-L12",
+  "session_id": "2026-06-03-full-score-fix",
+  "session_started_at": "2026-06-03T02:35:00Z",
+  "ttfv_seconds": 180,
+  "_comment_ttfv": "Time-to-First-Verification: seconds from session start to first passing test (L06 KPI). 180s = 3min for this session.",
+  "latest_handoff": ".codebase/IMPLEMENTATION_HANDOFF.md",
+  "latest_recovery_point": "Full Score Harness Fix — feature registry + observability",
+  "required_verification": [
+    "npm run verify",
+    "npm run eval",
+    "npm run pack:check",
+    "node tests/unit/feature_registry.test.js",
+    "node scripts/cold-start-check.js",
+    "node bin/genesis-harness.js docs-gate",
+    "node bin/genesis-harness.js leanctx"
+  ],
   "history": [
     {
-      "from": "INIT",
-      "to": "REQUIREMENTS_GATHERING",
-      "reason": "Started Gathering",
-      "timestamp": "2026-05-31T05:39:53.706Z"
-    },
-    {
-      "from": "REQUIREMENTS_GATHERING",
-      "to": "PLANNING",
-      "reason": "p",
-      "timestamp": "2026-05-31T05:51:07.765Z"
-    },
-    {
-      "from": "PLANNING",
-      "to": "IMPLEMENTATION",
-      "reason": "i",
-      "timestamp": "2026-05-31T05:51:07.883Z"
+      "from": "VERIFICATION",
+      "to": "COMPLETED",
+      "reason": "Harness drift gate hardening completed with source-of-truth, handoff, state, and CLI smoke verification gates.",
+      "timestamp": "2026-06-03T08:31:59+07:00",
+      "session_id": "2026-06-03-drift-gate"
     },
     {
-      "from": "IMPLEMENTATION",
-      "to": "VERIFICATION",
-      "reason": "v",
-      "timestamp": "2026-05-31T05:51:08.001Z"
+      "from": "VERIFICATION",
+      "to": "COMPLETED",
+      "reason": "LeanCTX policy, CLI reporting, prompt sentinel thresholds, and portable npm-user command guidance added.",
+      "timestamp": "2026-06-03T09:06:31+07:00",
+      "session_id": "2026-06-03-leanctx"
     },
     {
       "from": "VERIFICATION",
       "to": "COMPLETED",
-      "reason": "testing complete transition",
-      "timestamp": "2026-05-31T05:53:47.517Z"
+      "reason": "LeanCTX policy auto-seeding added for install and npm postinstall without overwriting project custom policy.",
+      "timestamp": "2026-06-03T09:28:41+07:00",
+      "session_id": "2026-06-03-leanctx-seed"
+    },
+    {
+      "from": "COMPLETED",
+      "to": "EXECUTE",
+      "reason": "Started full harness evaluation and score fix: L08 feature registry, L11 observability live, L04 instruction size, L03 cold-start, L05 session boundary, L07 scope, L09 victory blocker, L12 known problems.",
+      "timestamp": "2026-06-03T02:35:00Z",
+      "session_id": "2026-06-03-full-score-fix"
     }
   ],
-  "context": {},
+  "context": {
+    "score_target": "110/110",
+    "package_version": "0.1.7",
+    "verification_owner": "scripts/run-evals.sh",
+    "context_policy": ".codebase/context-policy.json",
+    "evaluation_report": ".codebase/../artifacts/harness_evaluation_report.md"
+  },
   "pending_tasks": []
-}
+}

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.
 ---
 
@@ -44,3 +44,8 @@ Changing dependency direction silently, documenting intent without tests, and sc
 ## Recovery workflow
 If architecture drift is found, stop feature work, create a failing boundary test, update the contract, then repair the smallest module slice.
 
+## MCP Automation Requirements
+
+To ensure that architectural decisions are properly contextualized and persisted across the entire lifecycle of the project, you **MUST** use the following MCP server:
+1. **`@modelcontextprotocol/server-memory`**: Use this MCP tool to automatically query the Knowledge Graph for past architectural decisions, trade-offs, and boundary definitions before making any new system-wide changes. After establishing a new architecture rule, you must save it to the memory graph.
+

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."
 ---
 
@@ -161,13 +161,13 @@ Update `.codebase` memory after meaningful changes.
    - Update documentation if behavior changed
 ```
 
-## Auto-Trigger Workflow (Post /fix-bug)
+## Auto-Trigger Workflow (Post /fix-bug or Heal Directive)
 
-When `/fix-bug` completes successfully:
+When `/fix-bug` completes successfully, or when you receive the `[AGENT_DIRECTIVE] TESTS FAILED` from `genesis-harness heal`:
 
 ```yaml
-Hook: PostToolUse → "/fix-bug completed"
-Action: Activate genesis-debug-guide
+Hook: PostToolUse → "/fix-bug completed" OR "[AGENT_DIRECTIVE] TESTS FAILED" printed to stdout.
+Action: Activate genesis-debug-guide. Do NOT stop until tests pass.
 
 1. Fix Verification (5 min):
    - Run: npm test (or equivalent)
@@ -400,6 +400,12 @@ If debugging effort exceeds 30 minutes:
    - Check GitHub issues/PRs for related bugs
 ```
 
+## MCP Automation Requirements
+
+To systematically isolate and resolve bugs, you **MUST** use the following MCP servers:
+1. **`@modelcontextprotocol/server-puppeteer`**: For any UI, E2E, or visual bug, use this MCP tool to automatically navigate to the local dev server, interact with the UI, reproduce the bug, capture the browser console logs, and take screenshots for Vision analysis.
+2. **`@modelcontextprotocol/server-memory`**: Query the Knowledge Graph to see if this bug is a known regression or if a similar issue has been resolved in the past.
+
 ## Integration with Genesis Harness
 
 **Works with**:

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.