codex-genesis-harness 0.1.7 → 0.1.8

package/README.EN.md

@@ -27,6 +27,17 @@
 
 ---
 
+## 💖 Support the Project (Donate)
+
+This project is open-source and developed with passion. If you find **Genesis Codex Harness** helpful and it saves you time, consider buying me a coffee to keep the momentum going:
+
+- **Momo (Vietnam)**: `0865814259`
+- **PayPal**: *(Will be updated later)*
+
+Thank you so much for supporting the development of this project! ❤️
+
+---
+
 ## 🎯 Why Genesis? (ROI in 3 minutes)
 
 ### Before Genesis ❌
@@ -133,16 +144,27 @@ Genesis Codex Harness introduces five groundbreaking architectural subsystems to
 
 ---
 
-## 🚀 Next-Gen Harness Engineering Upgrades (v0.1.7)
+## 🚀 Next-Gen Harness Engineering Upgrades (v0.1.8)
 
-Genesis v0.1.7 introduces five advanced, state-of-the-art tools under `scripts/` to enforce type-safety, automate tests, establish visual-code integrity, protect token consumption, and enable self-healing loop memory recall:
+Genesis v0.1.8 introduces five advanced, state-of-the-art tools under `scripts/` to enforce type-safety, automate tests, establish visual-code integrity, protect token consumption, and enable self-healing loop memory recall:
 
 1. **Visual Architecture AST Sync (`scripts/spec_visual_sync.js`)**: Bidirectional compiler that syncs Mermaid ERD database diagrams (`database-erd.mmd`) to API contracts JSON schemas (`contracts/api/`) and vice-versa, establishing absolute visual-to-code design integrity.
 2. **Contract-Driven Test Auto-Generator (`scripts/test_generator.js`)**: Automatically compiles fully executable Mocha/Jest integration test suites in `tests/integration/` directly from your API contracts JSON response schemas, providing instant TDD "RED" skeletons.
 3. **AST Contract-Code Integrity Gate (`scripts/contract_integrity_gate.js`)**: Static analysis checker that programmatically validates implementation code properties against API contract JSON schemas at FSM transition boundaries, locking state transitions if data type mismatches or missing properties are detected.
-4. **Pre-emptive Prompt Sentinel (`scripts/prompt_sentinel.js`)**: Real-time token budget monitor. Calculates token weights before calling LLM, pre-emptively halting runaway commands, and executing auto-compaction and log pruning when capacity thresholds (e.g. 20k tokens) are crossed.
+4. **Pre-emptive Prompt Sentinel (`scripts/prompt_sentinel.js`)**: Real-time token budget monitor. Calculates token weights before calling LLM, pre-emptively halting runaway commands, and executing auto-compaction and log pruning when the LeanCTX threshold in `.codebase/context-policy.json` is crossed.
 5. **Self-Healing Lessons-Learned Recall (`scripts/healing_telemetry.js`)**: Telemetry system that records compiler/test failure signatures and applied corrective code edits in `.codebase/failures/lessons_learned.md`. The self-healing loop recalls these recorded fixes on identical error signatures, bypassing iterations to achieve immediate **1-turn recovery**.
 
+### LeanCTX + Optional Local Wrappers
+
+Genesis ships a portable LeanCTX policy at `.codebase/context-policy.json` and exposes it through:
+
+```bash
+genesis-harness leanctx
+genesis-harness prime
+```
+
+`npm install` / `genesis-harness install` seeds the policy into the current project when a project root is detected, and never overwrites an existing custom policy. The `leanctx` command is only for inspection. Npm users keep using portable commands such as `genesis-harness sync`, `genesis-harness docs-gate`, and `npm run verify`. When `rtk` exists on a developer machine, Genesis reports it as an optional local wrapper only; it is not a public dependency.
+
 ---
 
 ## 🔬 Research-First Guarantee (NEW)
@@ -599,7 +621,7 @@ Genesis:
 
 ---
 
-## 📚 21 Skills (All Available)
+## 📚 25 Skills (All Available)
 
 Each skill follows the standard naming convention in `.codex/skills/`:
 
@@ -626,6 +648,10 @@ Each skill follows the standard naming convention in `.codex/skills/`:
 | **genesis-design-spec** | Define and manage design tokens and theme consistency | Standardizing design systems |
 | **genesis-harness-engineering** | Build test frameworks, harness structures, and test fixtures | Setting up test suites |
 | **spec-impact-engine** | Evaluate the blast radius of proposed specification changes | Assessing spec adjustments |
+| **genesis-executing-plans** | Strictly follow the approved execution plan and task.md | Implementing features via plan |
+| **genesis-test-driven-development** | Enforce TDD (Red -> Green -> Refactor) and test verification | Writing logic or bug fixes |
+| **genesis-verification-before-completion** | Require evidence and script execution before task completion | Finalizing any autonomous task |
+| **genesis-using-git-worktrees** | Isolate destructive or large architectural changes | High-risk refactoring |
 
 ---
 
@@ -734,17 +760,6 @@ npm run pack:check      # Check npm package
 
 ---
 
-## 💖 Support the Project (Donate)
-
-This project is open-source and developed with passion. If you find **Genesis Codex Harness** helpful and it saves you time, consider buying me a coffee to keep the momentum going:
-
-- **Momo (Vietnam)**: `0865814259`
-- **PayPal**: *(Will be updated later)*
-
-Thank you so much for supporting the development of this project! ❤️
-
----
-
 ## 🔗 Resources
 
 - **GitHub**: [codex-genesis-harness](https://github.com/tuanpham09/codex-genesis-harness)
@@ -761,7 +776,7 @@ Thank you so much for supporting the development of this project! ❤️
 - ✅ **Skills**: 25 fully implemented & verified (added 5-Phase MVP Roadmap planner, advanced self-healing and compaction engines)
 - ✅ **Test Coverage**: 80%+ required
 - ✅ **Token Savings**: 40-60%
-- ✅ **Production Ready**: Yes (v0.1.7)
+- ✅ **Production Ready**: Yes (v0.1.8)
 - ✅ **Auto-Research Enforcement**: Active
 - ✅ **Auto-Debug Verification**: Active
 - ✅ **Auto-Spec-Propagation**: Active
@@ -773,7 +788,7 @@ Thank you so much for supporting the development of this project! ❤️
 
 MIT License - See [LICENSE](LICENSE)
 
-**Genesis Codex Harness** - Build production software with Codex | v0.1.7 | June 2026
+**Genesis Codex Harness** - Build production software with Codex | v0.1.8 | June 2026
 
 ---
 

package/README.VI.md

@@ -26,6 +26,17 @@
 
 ---
 
+## 💖 Ủng Hộ Dự Án (Donate)
+
+Dự án này là mã nguồn mở và được phát triển hoàn toàn vì đam mê. Nếu bạn thấy **Genesis Codex Harness** hữu ích và giúp bạn tiết kiệm thời gian, bạn có thể mời tôi một ly cafe để tiếp thêm động lực phát triển nhé:
+
+- **Momo**: `0865814259`
+- **PayPal**: *(Sẽ cập nhật sau)*
+
+Cảm ơn bạn rất nhiều vì đã đồng hành cùng sự phát triển của dự án! ❤️
+
+---
+
 ## 🎯 Tại Sao Dùng Genesis? (ROI trong 3 phút)
 
 ### Trước Genesis ❌
@@ -132,15 +143,27 @@ Genesis Codex Harness giới thiệu 5 phân hệ kỹ thuật mang tính đột
 
 ---
 
-## 🚀 Nâng Cấp Kỹ Nghệ Harness Thế Hệ Mới (v0.1.7)
+## 🚀 Nâng Cấp Kỹ Nghệ Harness Thế Hệ Mới (v0.1.8)
 
-Phiên bản Genesis v0.1.7 giới thiệu năm công cụ cao cấp, đột phá trong thư mục `scripts/` nhằm áp đặt an toàn kiểu dữ liệu, tự động hóa test, thiết lập sự đồng nhất giữa sơ đồ trực quan và mã nguồn, chủ động kiểm soát token và khôi phục nhanh bài học sửa lỗi của Ralph Loop:
+Phiên bản Genesis v0.1.8 giới thiệu sáu công cụ cao cấp, đột phá trong thư mục `scripts/` nhằm áp đặt an toàn kiểu dữ liệu, tự động hóa test, thiết lập sự đồng nhất giữa sơ đồ trực quan và mã nguồn, chủ động kiểm soát token, khôi phục nhanh bài học sửa lỗi và hỗ trợ lập trình UI thần tốc:
 
 1. **Đồng bộ Sơ đồ Trực quan 2 Chiều (`scripts/spec_visual_sync.js`)**: Trình biên dịch hai chiều tự động đồng bộ hóa sơ đồ cơ sở dữ liệu ERD Mermaid (`database-erd.mmd`) sang các tệp JSON API contracts (`contracts/api/`) và ngược lại, bảo vệ tính nhất quán thiết kế tuyệt đối.
 2. **Trình Tự Động Sinh Test từ Hợp Đồng (`scripts/test_generator.js`)**: Tự động biên dịch và tạo cấu trúc các bộ kiểm thử tích hợp (Node.js/Jest) hoàn chỉnh tại `tests/integration/` trực tiếp từ các file response contract JSON, hỗ trợ lập tức kịch bản TDD "RED" skeleton.
 3. **Cổng Kiểm Soát Đồng Nhất Kiểu Dữ Liệu Tĩnh (`scripts/contract_integrity_gate.js`)**: Trình phân tích tĩnh chủ động đối chiếu mã nguồn thực tế với JSON API contract khi FSM chuyển trạng thái, khóa cứng tiến trình build/commit nếu phát hiện trường dữ liệu bị thiếu hoặc sai lệch kiểu dữ liệu.
-4. **Vệ Binh Tiền Trảm Token Chủ Động (`scripts/prompt_sentinel.js`)**: Bộ giám sát dung lượng token thời gian thực. Sentinel đo lường tải lượng token trước khi gọi LLM, chủ động tạm dừng các lệnh quá nặng và kích hoạt nén FSM/dọn logs khi dung lượng chạm ngưỡng an toàn (ví dụ: 20k tokens).
+4. **Vệ Binh Tiền Trảm Token Chủ Động (`scripts/prompt_sentinel.js`)**: Bộ giám sát dung lượng token thời gian thực. Sentinel đo lường tải lượng token trước khi gọi LLM, chủ động tạm dừng các lệnh quá nặng và kích hoạt nén FSM/dọn logs khi dung lượng chạm ngưỡng LeanCTX trong `.codebase/context-policy.json`.
 5. **Tự Động Thu Hồi Bài Học Sửa Lỗi (`scripts/healing_telemetry.js`)**: Hệ thống ghi chép lịch sử chữ ký lỗi và mã nguồn sửa lỗi thành công vào `.codebase/failures/lessons_learned.md`. Vòng lặp Ralph Loop sẽ đối sánh và tái sử dụng trực tiếp các phương án sửa lỗi này khi gặp lỗi tương ứng, đạt hiệu suất **tự khắc phục lỗi chỉ trong đúng 1 turn**.
+6. **Aesthetic Vibe Mode (`VIBE_MODE=1`)**: Một hệ thống Triage linh hoạt cho phép AI tự động bỏ qua các bài test nghiêm ngặt (TDD/Contract) khi người dùng chỉ muốn chỉnh sửa giao diện thẩm mỹ (CSS/UI). Mọi vi phạm lách luật đều được ghi chép ngầm vào `.codebase/TECH_DEBT.md` để xử lý sau.
+
+### LeanCTX + wrapper local tùy chọn
+
+Genesis cài kèm policy LeanCTX portable tại `.codebase/context-policy.json` và cung cấp:
+
+```bash
+genesis-harness leanctx
+genesis-harness prime
+```
+
+`npm install` / `genesis-harness install` sẽ tự seed policy vào project hiện tại khi phát hiện project root, và không ghi đè policy đã custom. Lệnh `leanctx` chỉ để xem/kiểm tra policy. Người dùng cài từ npm vẫn dùng lệnh chuẩn như `genesis-harness sync`, `genesis-harness docs-gate`, `npm run verify`. Nếu máy dev có `rtk`, Genesis chỉ tự nhận diện và hiển thị như wrapper local tùy chọn; `rtk` không phải dependency công khai.
 
 ---
 
@@ -599,7 +622,7 @@ Genesis:
 
 ---
 
-## 📚 21 Skills (Tất Cả)
+## 📚 25 Skills (Tất Cả)
 
 Mỗi skill tuân theo naming quy chuẩn trong thư mục `.codex/skills/`:
 
@@ -626,6 +649,10 @@ Mỗi skill tuân theo naming quy chuẩn trong thư mục `.codex/skills/`:
 | **genesis-design-spec** | Thiết lập Design System và Design Tokens | Đồng bộ thiết kế hệ thống |
 | **genesis-harness-engineering** | Xây dựng cơ sở hạ tầng test và dữ liệu mẫu | Setup test framework |
 | **spec-impact-engine** | Công cụ đánh giá mức độ ảnh hưởng của thay đổi spec | Kiểm tra độ tương thích |
+| **genesis-executing-plans** | Tuân thủ chặt chẽ bản kế hoạch đã duyệt và task.md | Triển khai theo plan đã chốt |
+| **genesis-test-driven-development** | Ép buộc tuân thủ TDD (Red -> Green -> Refactor) | Viết logic mới hoặc sửa lỗi |
+| **genesis-verification-before-completion** | Bắt buộc chạy kịch bản kiểm định trước khi xong việc | Đóng gói/hoàn tất đầu mục |
+| **genesis-using-git-worktrees** | Cô lập môi trường code bằng git worktree an toàn | Đổi cấu trúc/refactor diện rộng |
 
 ---
 
@@ -634,7 +661,7 @@ Mỗi skill tuân theo naming quy chuẩn trong thư mục `.codex/skills/`:
 | Tài Liệu | Mục Đích | Thời Gian |
 |----------|---------|----------|
 | [MODEL_ALLOCATION.md](.codex/MODEL_ALLOCATION.md) | Tại sao Codex là primary | 5 phút |
-| [SKILLS_INDEX.md](.codex/SKILLS_INDEX.md) | Chi tiết 19 skills | 20 phút |
+| [SKILLS_INDEX.md](.codex/SKILLS_INDEX.md) | Chi tiết 25 skills | 20 phút |
 | [SKILLS_NAMING_GUIDE.md](.codex/SKILLS_NAMING_GUIDE.md) | Convention naming | 5 phút |
 | [FILE_NAMING_CLARIFICATION.md](.codebase/FILE_NAMING_CLARIFICATION.md) | Giải thích file naming | 5 phút |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Cách đóng góp | 10 phút |
@@ -726,17 +753,6 @@ npm run eval            # Chạy evaluation
 
 ---
 
-## 💖 Ủng Hộ Dự Án (Donate)
-
-Dự án này là mã nguồn mở và được phát triển hoàn toàn vì đam mê. Nếu bạn thấy **Genesis Codex Harness** hữu ích và giúp bạn tiết kiệm thời gian, bạn có thể mời tôi một ly cafe để tiếp thêm động lực phát triển nhé:
-
-- **Momo**: `0865814259`
-- **PayPal**: *(Sẽ cập nhật sau)*
-
-Cảm ơn bạn rất nhiều vì đã đồng hành cùng sự phát triển của dự án! ❤️
-
----
-
 ## 🔗 Tài Nguyên
 
 - **GitHub**: [codex-genesis-harness](https://github.com/tuanpham09/codex-genesis-harness)
@@ -750,10 +766,10 @@ Cảm ơn bạn rất nhiều vì đã đồng hành cùng sự phát triển c
 
 - ✅ **Architecture**: 10/10 (research-first + auto-debug + auto-spec-propagation + auto-docs + validation gates)
 - ✅ **Codex-Only Enforcement**: 100%
-- ✅ **21 Skills**: Hoàn toàn kế thừa và triển khai đầy đủ (đã bổ sung lộ trình 5-Phase MVP, tự chữa lành & nén context)
+- ✅ **25 Skills**: Hoàn toàn kế thừa và triển khai đầy đủ (đã bổ sung lộ trình 5-Phase MVP, tự chữa lành & nén context)
 - ✅ **Test Coverage**: 80%+ required
 - ✅ **Token Savings**: 40-60%
-- ✅ **Production Ready**: Yes (v0.1.7)
+- ✅ **Production Ready**: Yes (v0.1.8)
 - ✅ **Auto-Research Enforcement**: Active
 - ✅ **Auto-Debug Verification**: Active
 - ✅ **Auto-Spec-Propagation**: Active
@@ -765,7 +781,7 @@ Cảm ơn bạn rất nhiều vì đã đồng hành cùng sự phát triển c
 
 MIT License - Xem [LICENSE](LICENSE)
 
-**Genesis Codex Harness** - Xây dựng phần mềm production với Codex | v0.1.7 | Tháng 6, 2026
+**Genesis Codex Harness** - Xây dựng phần mềm production với Codex | v0.1.8 | Tháng 6, 2026
 
 ---
 

package/README.md

@@ -13,6 +13,17 @@
 
 ---
 
+## 💖 Support the Project (Donate)
+
+This project is open-source and developed purely out of passion. If you find **Genesis Codex Harness** helpful and it saves you time, you can buy me a coffee to keep the development going:
+
+- **Momo**: `0865814259`
+- **PayPal**: *(Coming soon)*
+
+Thank you so much for your support! ❤️
+
+---
+
 ## ⚡ Core Pillars at a Glance
 
 *   🗺️ **Structured 5-Phase MVP Roadmap (`genesis-mvp-planning`):** Guarantees a decision-complete path to production. Genesis structures project delivery across 5 standard MVP phases (Foundation/API Core, Auth/Security, Core Features, Integrations, and Production Readiness), ensuring core infrastructure is verified before writing feature code.
@@ -30,8 +41,8 @@ To cater to all developers, Genesis features separate, highly exhaustive step-by
 
 | Language | Primary Link | Content Included |
 | :--- | :--- | :--- |
-| 🇬🇧 **English** | [README.EN.md](README.EN.md) | Exhaustive runbooks, all 21 skill details, learning paths, & production workflows. |
-| 🇻🇳 **Tiếng Việt** | [README.VI.md](README.VI.md) | Cẩm nang chi tiết bằng Tiếng Việt, giải nghĩa 21 skills, quy trình TDD chuẩn. |
+| 🇬🇧 **English** | [README.EN.md](README.EN.md) | Exhaustive runbooks, all 25 skill details, learning paths, & production workflows. |
+| 🇻🇳 **Tiếng Việt** | [README.VI.md](README.VI.md) | Cẩm nang chi tiết bằng Tiếng Việt, giải nghĩa 25 skills, quy trình TDD chuẩn. |
 
 ---
 
@@ -67,7 +78,7 @@ graph TD
     VL -- Test Passes / Green --> VG[4. Zero-Drift Validation Gate]
     VG -- Git Diff Spec Warning --> Synced[5. Auto-Docs & State Compaction]
     Synced --> Complete([COMPLETED State])
-    
+
     subgraph Harness Runtime Shell (FSM-Driven)
         RF
         TDD
@@ -76,7 +87,7 @@ graph TD
         VG
         Synced
     end
-    
+
     subgraph Memory & Context Safeguards
         Compaction[(Context Compaction)] <--> Synced
         Offload[(Tool Log Offloader)] <--> VL
@@ -94,15 +105,27 @@ Genesis is built on five core, state-of-the-art technological breakthroughs that
 
 ---
 
-## 🚀 Next-Gen Harness Engineering Upgrades (v0.1.7)
+## 🚀 Next-Gen Harness Engineering Upgrades (v0.1.8)
 
-Genesis v0.1.7 introduces five advanced, state-of-the-art tools under `scripts/` to enforce type-safety, automate tests, establish visual-code integrity, protect token consumption, and enable self-healing loop memory recall:
+Genesis v0.1.8 introduces six advanced, state-of-the-art tools under `scripts/` to enforce type-safety, automate tests, establish visual-code integrity, protect token consumption, enable self-healing loop memory recall, and provide agile UI iteration:
 
 1. **Visual Architecture AST Sync (`scripts/spec_visual_sync.js`)**: Bidirectional compiler that syncs Mermaid ERD database diagrams (`database-erd.mmd`) to API contracts JSON schemas (`contracts/api/`) and vice-versa, establishing absolute visual-to-code design integrity.
 2. **Contract-Driven Test Auto-Generator (`scripts/test_generator.js`)**: Automatically compiles fully executable Mocha/Jest integration test suites in `tests/integration/` directly from your API contracts JSON response schemas, providing instant TDD "RED" skeletons.
 3. **AST Contract-Code Integrity Gate (`scripts/contract_integrity_gate.js`)**: Static analysis checker that programmatically validates implementation code properties against API contract JSON schemas at FSM transition boundaries, locking state transitions if data type mismatches or missing properties are detected.
 4. **Pre-emptive Prompt Sentinel (`scripts/prompt_sentinel.js`)**: Real-time token budget monitor. Calculates token weights before calling LLM, pre-emptively halting runaway commands, and executing auto-compaction and log pruning when capacity thresholds (e.g. 20k tokens) are crossed.
 5. **Self-Healing Lessons-Learned Recall (`scripts/healing_telemetry.js`)**: Telemetry system that records compiler/test failure signatures and applied corrective code edits in `.codebase/failures/lessons_learned.md`. The self-healing loop recalls these recorded fixes on identical error signatures, bypassing iterations to achieve immediate **1-turn recovery**.
+6. **Aesthetic Vibe Mode (`VIBE_MODE=1`)**: A dynamic Triage engine that allows the AI to bypass strict PEV loops and TDD blockers exclusively for pure UI/CSS aesthetic changes. Bypassed failures are seamlessly routed to `.codebase/TECH_DEBT.md` for later reconciliation.
+
+### LeanCTX + Optional Local Wrappers
+
+Genesis ships a portable LeanCTX policy at `.codebase/context-policy.json` and exposes it through:
+
+```bash
+genesis-harness leanctx
+genesis-harness prime
+```
+
+`npm install` / `genesis-harness install` seeds the policy into the current project when a project root is detected, and never overwrites an existing custom policy. The `leanctx` command is only for inspection. Public npm usage and CI commands stay portable (`genesis-harness sync`, `genesis-harness docs-gate`, `npm run verify`). If `rtk` is installed locally, Genesis reports it as an optional wrapper for developer machines only; it is not required for npm users.
 
 ---
 
@@ -146,7 +169,7 @@ After installation, simply type standard commands in your Codex chat interface t
   ├── genesis-api-contract/               # Enterprise API contract designer
   ├── genesis-spec-propagation/           # Automated spec propagation engine
   ├── genesis-planning/                   # 5-Phase MVP roadmap planner
-  └── ... (15 more skills, total 21 skills)
+  └── ... (19 more skills, total 25 skills)
 
 .codebase/                                # Persistent repository memory system
 contracts/                                # Enterprise API, UI, and Data contracts
@@ -158,13 +181,28 @@ observability/                            # Run records and architectural ADR lo
 
 ---
 
+## 🔌 MCP Server Configuration (Optional)
+
+To supercharge the agent's research and debugging capabilities, you can optionally configure MCP (Model Context Protocol) servers.
+We provide two ways to integrate them:
+
+### Option 1: Global Installation
+Run the built-in setup script to install recommended MCPs globally:
+```bash
+npm run mcp:setup
+```
+This installs essential MCPs like Puppeteer (Browser/UI tests), GitHub, and SQLite (Vector Memory).
+
+### Option 2: Dynamic Execution (Agent Config)
+If you prefer not to install them globally, you can configure your Agent Client (e.g., Claude Desktop, Hermes, Cursor) to run them dynamically. See the `mcp.example.json` file in the repository root for configuration snippets.
+
 ## 📊 Project Status & Versioning
 
 - ✅ **Architecture Rating**: `10/10` (Enforced research-first + self-healing + spec-propagation)
 - ✅ **Codex-Only Enforcement**: `100%`
-- ✅ **Skills Matrix**: 21 fully implemented, structured, and verified skills
+- ✅ **Skills Matrix**: 25 fully implemented, structured, and verified skills
 - ✅ **Token Caching Savings**: `40% to 60%` verified per enterprise project
-- ✅ **Stability & Readiness**: Production Ready (`v0.1.7` - June 2026)
+- ✅ **Stability & Readiness**: Production Ready (`v0.1.8` - June 2026)
 
 ---
 
@@ -174,5 +212,5 @@ Licensed under the [MIT License](LICENSE). Contributions, bug reports, and featu
 
 ---
 
-**Genesis Codex Harness** v0.1.7 | June 2026
+**Genesis Codex Harness** v0.1.8 | June 2026
 👉 **[Full English Guide](README.EN.md) | [Tiếng Việt Hướng Dẫn](README.VI.md)**

package/VERSION

@@ -1,2 +1,2 @@
-0.1.7
+0.1.8