codex-harness-engineering 0.1.5 → 0.1.6

package/AGENTS.md

@@ -11,7 +11,7 @@ Chỉ dùng năm bài sau:
 - `[S2]` Anthropic, "Effective harnesses for long-running agents".
 - `[S3]` Anthropic, "Building effective agents".
 - `[S4]` Anthropic, "Harness design for long-running application development".
-- `[S5]` Google DeepMind, "AutoHarness: Improving LLM Agents by Automatically Synthesizing a Code Harness" & Google Cloud agent engineering practices.
+- `[S5]` Google DeepMind, "AutoHarness: improving LLM agents by automatically synthesizing a code harness".
 
 Không thêm resource, citation, paper, DOI, benchmark, hoặc blog khác nếu người
 dùng chưa yêu cầu mở rộng phạm vi.
@@ -25,19 +25,31 @@ dùng chưa yêu cầu mở rộng phạm vi.
   `docs/harness-engineering/implementation-playbook.md`.
 - Danh mục nguồn đã xác minh nằm ở `docs/harness-engineering/sources.md`.
 - Skill thực hành tạo harness nằm ở `skills/creator-harness/SKILL.md`.
+- Skill ghi mistake thành lesson và promote rule lặp lại nằm ở
+  `skills/lessons-harness/SKILL.md`.
 
 ## Bắt đầu session
 
-1. Đọc `README.md`, `progress.md`, và `feature_list.json`.
-2. Xem lịch sử git gần nhất để nhận biết thay đổi đang tiếp tục.
-3. Chạy `./init.sh` để kiểm tra baseline rẻ nhất trước khi sửa.
-4. Khi task thay đổi hành vi, guardrail, package, script, test, skill, hoặc
+1. Đọc `README.md`, `progress.md`, và `feature_list.json`. Đây là file nóng,
+   chỉ giữ entry gần nhất và capability đang active; lịch sử cũ nằm ở
+   `memory/progress/` và `memory/features-archive.json`, chỉ đọc khi cần tra
+   cứu. Khi `progress.md` vượt 400 dòng, verify sẽ fail và yêu cầu chạy
+   `node templates/harness/rotate-state.mjs .` để archive.
+2. Đọc `lessons.md` để biết mistake đang chờ promote và rule rút ra từ session
+   trước; lesson đã promote nằm ở `memory/lessons/`.
+3. Xem lịch sử git gần nhất để nhận biết thay đổi đang tiếp tục.
+4. Chạy `./init.sh` để kiểm tra baseline rẻ nhất trước khi sửa.
+5. Khi task thay đổi hành vi, guardrail, package, script, test, skill, hoặc
    quy tắc agent, chỉ đánh dấu feature đã verify sau khi lệnh kiểm tra liên quan
    pass.
-5. Với các thay đổi ở mục 4, luôn cập nhật `feature_list.json` và `progress.md`
+6. Với các thay đổi ở mục 5, luôn cập nhật `feature_list.json` và `progress.md`
    trước khi hoàn tất, kể cả task nhỏ. Chỉ task chỉnh nội dung nghiên cứu thuần
    túy mới có thể chỉ ghi `progress.md` khi kéo dài. Mục `Relevant files` trong
    entry mới nhất của progress phải liệt kê các artifact hành vi đã đổi.
+7. Khi một gate, test, hoặc review bắt mistake do agent gây ra, dùng
+   `$lessons-harness` để ghi lesson vào `lessons.md` trước khi kết thúc
+   session. Khi cùng một rule xuất hiện lần thứ hai, promote nó vào
+   `AGENTS.md` hoặc `scripts/verify-harness.mjs`.
 
 ## Lệnh chuẩn
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thoai Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -27,6 +27,9 @@ Kho này biến năm nguồn thành một harness tối thiểu cho Codex:
    planner, evaluator, hoặc orchestration mặc định [S3], [S4].
 4. Cung cấp skill thực hành để tạo, chốt scope, verify, và cleanup harness trong
    công việc dài hạn của Codex [S1], [S2], [S4], [S5].
+5. Đóng vòng lặp học từ mistake: ghi lesson khi gate hoặc review bắt lỗi, và
+   promote rule lặp lại thành guardrail cơ học để Codex không lặp lại lỗi cũ
+   ở session sau [S1], [S2], [S5].
 
 ## Năm nguồn duy nhất
 
@@ -36,21 +39,24 @@ Kho này biến năm nguồn thành một harness tối thiểu cho Codex:
 | `[S2]` | Anthropic, "Effective harnesses for long-running agents" | Mẫu state handoff cho agent dài hạn: feature list, progress file, setup, git history, và kiểm thử đầu-cuối |
 | `[S3]` | Anthropic, "Building effective agents" | Nguyên tắc bắt đầu đơn giản, phân biệt workflow với agent, và chỉ tăng complexity khi tradeoff đáng giá |
 | `[S4]` | Anthropic, "Harness design for long-running application development" | Planner-generator-evaluator, sprint contract, evaluator riêng, và QA runtime cho task ứng dụng dài |
-| `[S5]` | Google DeepMind, "AutoHarness: Improving LLM Agents by Automatically Synthesizing a Code Harness" & Google Cloud | AutoHarness tự động sinh lớp bọc thực thi chặn hành động lỗi, Trajectory Evaluation kiểm chứng vết chạy, LLM-as-a-judge và Meta-Evaluation (VeRO) tối ưu cấu trúc |
+| `[S5]` | Google DeepMind, "AutoHarness: improving LLM agents by automatically synthesizing a code harness" | AutoHarness tự động sinh lớp bọc thực thi chặn hành động không hợp lệ và sinh policy thành code tĩnh (code-as-policy) để giảm chi phí runtime |
 
 ## Bản đồ tài liệu
 
 | File | Mục đích |
 | --- | --- |
 | `docs/harness-engineering/index.md` | Mục lục và thứ tự đọc |
-| `docs/harness-engineering/research-note.md` | Bản tổng hợp nghiên cứu chính |
+| `docs/harness-engineering/research-note.md` | Bản white paper nguồn-truth |
 | `docs/harness-engineering/implementation-playbook.md` | Playbook triển khai harness cho repository |
 | `docs/harness-engineering/sources.md` | Metadata và bản đồ bằng chứng cho năm nguồn |
 | `skills/creator-harness/SKILL.md` | Skill thực hành tạo harness tối thiểu |
 | `skills/acceptance-contract/SKILL.md` | Skill chốt scope, tiêu chí done, và verification trước khi làm |
 | `skills/cleanup-harness/SKILL.md` | Skill cleanup có trigger, acceptance criteria, và rollback |
+| `skills/lessons-harness/SKILL.md` | Skill ghi mistake thành lesson và promote rule lặp lại thành guardrail cơ học |
 | `progress.md` | Trạng thái bền vững để session sau tiếp tục công việc |
 | `feature_list.json` | Danh sách capability harness và điều kiện verify |
+| `lessons.md` | Mistake đang chờ promote và rule rút ra từ đó |
+| `memory/README.md` | Contract của lớp lạnh và layout archive |
 | `init.sh` | Smoke test đầu session |
 
 ## Phát hành qua NPM
@@ -62,7 +68,7 @@ Chạy lệnh sau ở root của project muốn nhận docs:
 npx codex-harness-engineering init
 ```
 
-Lệnh này copy 3 skill vào `./.agents/skills` và copy docs vào
+Lệnh này copy 4 skill vào `./.agents/skills` và copy docs vào
 `./docs/harness-engineering` của project hiện tại. Nếu các target đã tồn tại,
 lệnh sẽ dừng để tránh ghi đè. Dùng `--force` khi muốn thay thế bản cũ:
 
@@ -70,6 +76,60 @@ lệnh sẽ dừng để tránh ghi đè. Dùng `--force` khi muốn thay thế
 npx codex-harness-engineering init --force
 ```
 
+Chạy `npx codex-harness-engineering init` để scaffold bộ harness tối thiểu
+cho developer theo chuẩn của playbook. `AGENTS.md`, `progress.md`,
+`feature_list.json`, `lessons.md`, `memory/README.md`, `init.sh`, và
+`verify-state.mjs` được tạo ở root của project từ template trong
+`templates/harness/`:
+
+```bash
+npx codex-harness-engineering init
+```
+
+`--harness` và `--starter-kit` vẫn được giữ như alias tương thích ngược.
+
+Sau khi scaffold, sửa `init.sh` thành lệnh setup + smoke test thật của project
+và điền mục Commands trong `AGENTS.md`. `init.sh` mặc định exit 1 cho tới khi
+được cấu hình để guardrail không pass giả. `node verify-state.mjs` là gate cơ
+học: nó fail khi working tree có thay đổi behavior mà thiếu cập nhật
+`feature_list.json`/`progress.md`, hoặc entry progress mới nhất không nêu tên
+file đã đổi.
+
+Scaffold này được viết cho workflow Codex: Codex tự đọc `AGENTS.md` ở đầu mỗi
+session (file này là bản đồ ngắn theo [S1], trỏ tới state và lệnh chuẩn), bốn
+skill cài ở `.agents/skills/` được gọi bằng `$acceptance-contract`,
+`$creator-harness`, `$cleanup-harness`, `$lessons-harness`, và mỗi session kết
+thúc bằng commit + entry `progress.md` làm recovery point cho session sau theo
+[S2].
+
+Thêm `--team` khi dự án cần một đội production theo mẫu
+planner-generator-evaluator của [S4]. Lệnh này scaffold cả harness và thư mục
+`team/` gồm `team/workflow.md` (pipeline plan → build → evaluate → ship), ba
+role contract trong `team/roles/` (planner, implementer, evaluator — mỗi role
+là một session Codex riêng, handoff qua artifact trong `team/sprints/`),
+`team/sprint-template.md`, và gate `team/verify-team.mjs` — sprint không thể
+mang `Status: done` nếu thiếu `evaluation.md` với `Verdict: pass` từ
+evaluator:
+
+```bash
+npx codex-harness-engineering init --team
+```
+
+Memory của harness chia hai lớp theo progressive disclosure [S1] để dự án kéo
+dài không làm phình file nóng: `progress.md`, `feature_list.json`, và
+`lessons.md` chỉ giữ entry gần nhất, capability đang active, và mistake/rule
+chưa promote; contract của lớp lạnh nằm ở `memory/README.md`; lịch sử cũ nằm
+ở `memory/progress/<YYYY-MM>.md`, `memory/features-archive.json`, và
+`memory/lessons/<YYYY-MM>.md`. Chạy `node rotate-state.mjs` để archive; gate
+`verify-state.mjs` tự fail khi `progress.md` hoặc `lessons.md` vượt budget
+400 dòng để nhắc rotate.
+
+`lessons.md` và skill `$lessons-harness` là vòng lặp học từ mistake: mỗi lần
+gate, test, hoặc review bắt lỗi do agent gây ra, agent ghi lesson với root
+cause và rule; khi cùng một rule lặp lại, rule được promote thành dòng trong
+`AGENTS.md` hoặc một check trong `verify-state.mjs` để mistake không lặp lại ở
+session sau [S1], [S5].
+
 Khi phát triển local:
 
 ```bash
@@ -106,7 +166,9 @@ Khi bắt đầu một task trong repo phần mềm khác, dùng kho này như h
    Codex.
 4. Dùng `skills/cleanup-harness/SKILL.md` khi throughput của Codex tạo drift,
    orphan, hoặc entropy cần cleanup định kỳ.
-5. Chỉ thêm evaluator, planner, hoặc sprint contract khi task thật sự có scope
+5. Dùng `skills/lessons-harness/SKILL.md` khi một gate, test, hoặc review bắt
+   lỗi do Codex gây ra; ghi lesson và promote rule lặp lại thành guardrail.
+6. Chỉ thêm evaluator, planner, hoặc sprint contract khi task thật sự có scope
    dài, chất lượng chủ quan, hoặc runtime khó tự đánh giá.
 
 ## Kết luận cốt lõi
@@ -114,7 +176,7 @@ Khi bắt đầu một task trong repo phần mềm khác, dùng kho này như h
 Từ năm bài này, harness engineering cho Codex không nên được hiểu là thêm nhiều
 agent mặc định. Nó là một lớp điều khiển gồm state bền vững, tool dễ đọc,
 acceptance criteria, kiểm thử runtime, evaluator khi cần, guardrail cơ học, dọn dẹp
-hệ thống, và các cơ chế tự động hóa hay đánh giá vết chạy.
+hệ thống, và cơ chế tự động tổng hợp lớp bọc thực thi.
 
 Nguyên tắc thực dụng:
 
@@ -125,7 +187,8 @@ Nguyên tắc thực dụng:
 4. Khi Codex tự đánh giá quá lạc quan, tách generator khỏi evaluator [S4].
 5. Khi throughput tạo drift, biến judgment lặp lại thành lint, test, rule, và
    cleanup có nhịp [S1].
-6. Khi quy tắc phức tạp, dùng AutoHarness tự sinh code wrapper để lọc hành vi và Trajectory Evaluation để giám sát chuỗi hành động của agent [S5].
+6. Khi quy tắc phức tạp, dùng AutoHarness tự sinh code wrapper để lọc hành vi
+   không hợp lệ trước khi thực thi [S5].
 
 ## Quy tắc cập nhật