codex-genesis-harness 0.1.7 → 0.1.8

package/.codebase/RECOVERY_POINTS.md

@@ -1,83 +1,22 @@
 # Recovery Points
 
-**Purpose**: Document where harness architecture implementation can be paused and resumed without losing context or creating inconsistencies.
-
-**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.
-
----
-
-## Quick Reference: Current Recovery Points
-
-| Phase | Status | Resumption File | Last Updated |
-|-------|--------|-----------------|--------------|
-| 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: Harness Verification Streamlining & Memory Evals
-
-**Status**: ✓ Complete  
-**Last Updated**: 2026-06-01  
-
-### What Happened
-
-- 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()`.
-
-### Safe State Confirmation
-
-The harness currently passes all structural tests cleanly.
-```bash
-# Verify structure
-./scripts/verify.sh
-
-# Verify regression
-./scripts/run-evals.sh
-
-# Dry-run package integrity
-npm run pack:check
-```
-
----
-
-## Rollback Points
-
-### If A Future Harness Evolution Breaks the CLI/Environment
-
-**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 checkout -- bin/genesis-harness.js scripts/verify.sh scripts/run-evals.sh
-npm install
-./scripts/verify.sh
-```
-
-**Rollback Level 2: Full Repository Reset**
-If tests are failing in a manner that contaminates local fixtures or memory:
-```bash
-git reset --hard HEAD
-git clean -fd
-npm install
-./scripts/verify.sh
-```
-
----
-
-## Checklist: Before Pausing Work on Harness Evolutions
-
-- [ ] `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
+A reverse-chronological log of stable states to return to if the current task corrupts the project.
 
 ---
 
-## Contact For Questions
-**Owner**: Codex Harness Engineering Team
-**Last Validated**: 2026-06-01
+## 2026-06-03T09:55:00+07:00: Full Score Harness Fix (110/110)
+- **Status**: Stable
+- **Git State**: Everything committed + new features added.
+- **Why it's stable**: All tests (`tests/unit/*.test.js`), `verify.sh`, `run-evals.sh`, and `cold-start-check.js` pass with exit code 0.
+- **How to recover**: `git reset --hard HEAD` (assuming commit happens immediately after this)
+- **Files added**: `features/REGISTRY.md`, `scripts/cold-start-check.js`, `scripts/check-scope.sh`, observability schemas/samples.
+
+## 2026-06-03T09:30:00+07:00: LeanCTX + CLI Postinstall Seed
+- **Status**: Stable
+- **Why it's stable**: `npm run verify` and `npm run eval` pass. `context-policy.json` successfully bootstrapped.
+- **How to recover**: Return to commit before the evaluation score fixes.
+
+## 2026-06-03T08:35:00+07:00: Harness Drift Gate Hardening
+- **Status**: Stable
+- **Why it's stable**: `npm run verify`, `npm run eval`, and `npm run pack:check` all pass.
+- **How to recover**: Revert to branch state before LeanCTX introduction.

package/.codebase/TECH_DEBT.md

@@ -0,0 +1,6 @@
+# Tech Debt Ledger
+
+This file logs structural rule violations, skipped tests, and out-of-scope modifications that were bypassed using `VIBE_MODE`.
+The AI and developers should periodically review this file to pay down technical debt.
+
+---

package/.codebase/TEST_MATRIX.md

@@ -2,10 +2,11 @@
 
 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.
+- `scripts/verify.sh`: repository harness structure, skill metadata, contracts, fixtures, harness smoke test, and `SKILL.md` progressive-disclosure line limit.
+- `scripts/run-evals.sh`: install/verify/uninstall regression checks, manifest route checks, sync-generated Mermaid relationship checks, hook docs-gate checks, LeanCTX policy checks, handoff/state freshness checks, `tests/unit/*.test.js`, and `tests/integration/*.test.js`.
+- `tests/integration/cli-smoke.test.js`: package CLI smoke for install/postinstall LeanCTX seeding, `path`, `status`, `docs`, `docs-gate`, `leanctx`, `prime`, and `sync` in temporary fixture repositories.
+- `tests/unit/prompt_sentinel.test.js`: LeanCTX-backed prompt sentinel threshold and truncation behavior.
 - `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/VISUAL_GRAPH.md

@@ -0,0 +1,127 @@
+# Visual Project Graph
+
+## Harness Relationship Map
+
+```mermaid
+flowchart LR
+  manifest[".codex-plugin/plugin.json"] --> skills[".codex/skills/*"]
+  package["package.json"] --> cli["bin/genesis-harness.js"]
+  package --> verify["scripts/verify.sh"]
+  package --> evals["scripts/run-evals.sh"]
+  cli --> install["install / postinstall"]
+  cli --> hooks["setup-hooks"]
+  hooks --> docsgate["genesis-harness docs-gate"]
+  docsgate --> docsync["check-docs-sync.sh"]
+  docsgate --> specsync["check-spec-changelog.sh"]
+  skills --> contracts["contracts/"]
+  skills --> fixtures["fixtures/"]
+  skills --> tests["tests/ + playwright/"]
+  skills --> memory[".codebase/"]
+  verify --> skills
+  verify --> contracts
+  verify --> fixtures
+  verify --> memory
+  evals --> install
+  evals --> cli
+  evals --> unit["tests/unit/*.test.js"]
+  evals --> integration["tests/integration/*.test.js"]
+  evals --> pack["npm pack smoke"]
+```
+
+## Skill Workflow Relationships
+
+```mermaid
+flowchart TD
+  harness["genesis-harness"] --> planning["genesis-planning"]
+  harness --> research["genesis-research-first"]
+  planning --> architecture["genesis-architecture"]
+  planning --> api["genesis-api-contract"]
+  planning --> design["genesis-design-spec"]
+  api --> apisync["genesis-api-sync"]
+  design --> ui["genesis-ui-ux-test"]
+  api --> specimpact["spec-impact-engine"]
+  specimpact --> specprop["genesis-spec-propagation"]
+  specprop --> docs["genesis-docs-automation"]
+  ui --> verifybefore["genesis-verification-before-completion"]
+  apisync --> verifybefore
+  docs --> verifybefore
+  verifybefore --> release["genesis-release"]
+  harness --> memorymap["genesis-codebase-map"]
+  harness --> observability["genesis-observability-automation"]
+```
+
+## Code Dependency Hints
+
+```mermaid
+flowchart TD
+  "tests/integration/cli-smoke.test.js" --> "assert"
+  "tests/integration/cli-smoke.test.js" --> "fs"
+  "tests/integration/cli-smoke.test.js" --> "os"
+  "tests/integration/cli-smoke.test.js" --> "path"
+  "tests/integration/cli-smoke.test.js" --> "child_process"
+  "tests/unit/contract_integrity_gate.test.js" --> "assert"
+  "tests/unit/contract_integrity_gate.test.js" --> "fs"
+  "tests/unit/contract_integrity_gate.test.js" --> "path"
+  "tests/unit/contract_integrity_gate.test.js" --> "child_process"
+  "tests/unit/healing_telemetry.test.js" --> "assert"
+  "tests/unit/healing_telemetry.test.js" --> "fs"
+  "tests/unit/healing_telemetry.test.js" --> "path"
+  "tests/unit/healing_telemetry.test.js" --> "child_process"
+  "tests/unit/prompt_sentinel.test.js" --> "assert"
+  "tests/unit/prompt_sentinel.test.js" --> "fs"
+  "tests/unit/prompt_sentinel.test.js" --> "path"
+  "tests/unit/prompt_sentinel.test.js" --> "child_process"
+  "tests/unit/spec_visual_sync.test.js" --> "assert"
+  "tests/unit/spec_visual_sync.test.js" --> "fs"
+  "tests/unit/spec_visual_sync.test.js" --> "path"
+  "tests/unit/spec_visual_sync.test.js" --> "child_process"
+  "tests/unit/test_generator.test.js" --> "assert"
+  "tests/unit/test_generator.test.js" --> "fs"
+  "tests/unit/test_generator.test.js" --> "path"
+  "tests/unit/test_generator.test.js" --> "child_process"
+  "bin/genesis-harness.js" --> "fs"
+  "bin/genesis-harness.js" --> "path"
+  "bin/genesis-harness.js" --> "child_process"
+  "bin/genesis-harness.js" --> "@babel/parser"
+  "bin/genesis-harness.js" --> "@babel/traverse"
+  "bin/genesis-harness.js" --> "child_process"
+```
+
+## .planning/ROADMAP.md Derived Feature Status
+
+```mermaid
+graph TD
+  classDef completed fill:#d4edda,stroke:#28a745,stroke-width:2px;
+  classDef inprogress fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
+  classDef pending fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
+  subgraph Role_0 ["Role: User"]
+    Task0["Roadmap task 0"]
+    class Task0 completed;
+    Task1["Roadmap task 1"]
+    class Task1 inprogress;
+    Task2["Roadmap task 2"]
+    class Task2 pending;
+  end
+  subgraph Role_1 ["Role: Admin"]
+    Task3["Roadmap task 3"]
+    class Task3 completed;
+    Task4["Roadmap task 4"]
+    class Task4 pending;
+    Task5["Roadmap task 5"]
+    class Task5 inprogress;
+  end
+  subgraph Role_2 ["Role: Analytics"]
+    Task6["Roadmap task 6"]
+    class Task6 pending;
+    Task7["Roadmap task 7"]
+    class Task7 pending;
+    Task8["Roadmap task 8"]
+    class Task8 inprogress;
+  end
+  Task0 --> Task1
+  Task0 --> Task2
+  Task2 --> Task4
+  Task2 --> Task5
+  Task4 --> Task6
+```
+

package/.codebase/context-policy.json

@@ -0,0 +1,68 @@
+{
+  "name": "leanctx-default",
+  "token_budget": 12000,
+  "_comment_token_budget": "Default conservative budget. Override in project .codebase/context-policy.json. For 128k-context models, set to 40000.",
+  "auto_scale": {
+    "enabled": false,
+    "note": "Set enabled=true and provide model_context_window to auto-calculate budgets. Formula: token_budget = model_context_window * 0.09 (9% for harness context leaves 91% for generation).",
+    "model_context_window": null,
+    "scale_factor": 0.09
+  },
+  "warn_at": 0.6,
+  "compact_at": 0.7,
+  "hard_stop_at": 0.85,
+  "layers": [
+    {
+      "name": "core",
+      "max_tokens": 2500,
+      "include": [
+        "AGENTS.md",
+        ".codex/SOUL.md",
+        ".codebase/CURRENT_STATE.md",
+        ".codebase/MODULE_INDEX.md",
+        ".codebase/TEST_MATRIX.md"
+      ]
+    },
+    {
+      "name": "active_context",
+      "max_tokens": 6500,
+      "include": [
+        ".codebase/COMPRESSED_CONTEXT.md",
+        ".codebase/VISUAL_GRAPH.md",
+        ".planning/STATE.md",
+        ".planning/ROADMAP.md",
+        "contracts/",
+        "fixtures/"
+      ]
+    },
+    {
+      "name": "deferred_reference",
+      "max_tokens": 3000,
+      "include": [
+        ".codex/skills/*/references/",
+        ".codex/skills/*/playbooks/",
+        ".codex/skills/*/checklists/",
+        "README*.md"
+      ]
+    }
+  ],
+  "defer_patterns": [
+    ".codex/skills/*/templates/**",
+    ".codex/skills/*/examples/**",
+    "playwright/**",
+    "observability/**",
+    "node_modules/**",
+    "dist/**",
+    "coverage/**"
+  ],
+  "portable_commands": [
+    "genesis-harness leanctx",
+    "genesis-harness sync",
+    "genesis-harness docs-gate",
+    "genesis-harness verify-gate",
+    "npm run verify",
+    "npm run eval",
+    "node scripts/cold-start-check.js"
+  ],
+  "wrapper_policy": "rtk optional when installed locally; public docs and CI must use portable commands."
+}

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-architecture/SKILL.md

@@ -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-debug-guide/SKILL.md

@@ -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**: