codex-harness-engineering 0.1.4 → 0.1.6

package/docs/harness-engineering/sources.md

@@ -1,7 +1,7 @@
 # Nguồn
 
-File này chỉ theo dõi bốn nguồn được phép dùng trong bản nghiên cứu hiện tại.
-Không thêm claim vào tài liệu nếu claim đó không ánh xạ tới một trong bốn nguồn
+File này theo dõi năm nguồn được phép dùng trong bản nghiên cứu hiện tại.
+Không thêm claim vào tài liệu nếu claim đó không ánh xạ tới một trong năm nguồn
 này hoặc không được đánh dấu rõ là diễn giải.
 
 ## Danh mục nguồn
@@ -9,23 +9,75 @@ này hoặc không được đánh dấu rõ là diễn giải.
 ### [S1] OpenAI
 
 - Tiêu đề: "Harness engineering: leveraging Codex in an agent-first world"
-- Tác giả: Ryan Lopopolo
-- Ngày xuất bản: 11 tháng 2, 2026
+- Tác giả: Ryan Lopopolo (Member of the Technical Staff)
+- Ngày xuất bản: 11 tháng 2, 2026 (bản clipping nội bộ ghi published 2026-05-27;
+  giữ Feb 2026 theo trích dẫn gốc — xem ghi chú cuối mục)
 - URL: https://openai.com/index/harness-engineering/
+- Bối cảnh: thí nghiệm 5 tháng (commit đầu cuối tháng 8/2025), team lái Codex để
+  ship một sản phẩm beta nội bộ ~1 triệu dòng code với **0 dòng code viết tay**;
+  ~1.500 PR đã merge; team từ 3 lên 7 kỹ sư, throughput ~3.5 PR/kỹ sư/ngày và
+  *tăng* khi team lớn lên; ước tính nhanh hơn ~10 lần so với viết tay.
 - Dùng cho:
-  - framing "humans steer, agents execute";
+  - framing "humans steer, agents execute": con người prioritize, dịch feedback
+    thành acceptance criteria, validate kết quả; khi agent vướng, hỏi "thiếu
+    capability nào và làm sao để agent thấy được + cưỡng chế được", rồi để chính
+    Codex viết bản sửa — không bao giờ tự sửa code tay;
   - harness engineering như thiết kế environment, intent specification, và
-    feedback loop quanh Codex;
-  - repository knowledge base như system of record;
-  - `AGENTS.md` như bản đồ, không phải cẩm nang khổng lồ;
-  - ưu tiên dependency, abstraction, và thông tin mà agent có thể inspect,
-    validate, và modify trực tiếp trong repo;
-  - application, browser, log, metric, và trace như tín hiệu agent đọc được;
-  - progressive disclosure cho tri thức trong repo và kiểm tra cơ học về
-    freshness/cross-link để giảm drift của tài liệu;
-  - cưỡng chế architecture và taste bằng lint, structural test, và custom rule;
-  - throughput, merge philosophy, autonomy, entropy, và cleanup định kỳ;
-  - cảnh báo rằng mức tự chủ phụ thuộc vào cấu trúc và tooling cụ thể của repo.
+    feedback loop quanh Codex; làm depth-first: chẻ goal lớn thành building block
+    (design, code, review, test) để mở khóa task phức tạp hơn;
+  - vòng lặp PR kiểu "Ralph Wiggum": Codex tự review local, xin thêm agent review
+    local + cloud, phản hồi feedback, lặp tới khi mọi reviewer hài lòng; review
+    đẩy gần như hoàn toàn sang agent-to-agent, human review không bắt buộc;
+  - application legibility: app bootable theo từng git worktree; nối Chrome
+    DevTools Protocol vào agent runtime + skill cho DOM snapshot/screenshot/
+    navigation để Codex tái hiện bug và validate fix; observability stack ephemeral
+    theo worktree, query log bằng LogQL và metric bằng PromQL, làm prompt kiểu
+    "service startup < 800ms" hay "không span nào > 2s" trở nên tractable;
+  - repository knowledge base có cấu trúc (`docs/` với design-docs, exec-plans,
+    product-specs, references llms.txt, ARCHITECTURE/QUALITY_SCORE/RELIABILITY…)
+    là system of record; plan là artifact hạng nhất, exec-plan kèm progress +
+    decision log được check-in;
+  - `AGENTS.md` như bản đồ / mục lục ngắn (~100 dòng) inject vào context, trỏ tới
+    nguồn sự thật sâu hơn — không phải encyclopedia một-file (one-big-AGENTS.md
+    thất bại vì: chiếm context, "everything important = nothing important", rot
+    nhanh, khó verify cơ học);
+  - progressive disclosure: agent bắt đầu từ entry point nhỏ ổn định rồi được chỉ
+    nơi xem tiếp; linter + CI validate knowledge base up-to-date/cross-linked,
+    cùng agent "doc-gardening" định kỳ quét doc cũ và mở PR sửa;
+  - agent legibility là mục tiêu: "thứ agent không truy cập được in-context coi
+    như không tồn tại" — phải đẩy context (kể cả thảo luận Slack) vào repo dạng
+    versioned artifact;
+  - ưu tiên dependency và abstraction có thể nội-hóa và lập luận in-repo; công
+    nghệ "boring" dễ model hơn; đôi khi rẻ hơn khi để agent tự reimplement một
+    phần thay vì lệ thuộc hành vi opaque upstream (vd tự viết map-with-concurrency
+    thay cho `p-limit`, tích hợp OpenTelemetry, 100% test coverage);
+  - cưỡng chế architecture và taste bằng invariant, không micromanage cài đặt:
+    mỗi business domain chia layer cố định, dependency chỉ đi "tiến"
+    `Types → Config → Repo → Service → Runtime → UI`, cross-cutting concern (auth,
+    connector, telemetry, feature flag) vào qua một interface duy nhất Providers;
+    enforce bằng custom linter (do Codex sinh) + structural test, error message
+    chèn luôn hướng dẫn remediation vào context; enforce boundary tập trung, cho
+    tự do cục bộ;
+  - throughput đổi merge philosophy: merge gate tối thiểu, PR ngắn hạn, test flake
+    xử lý bằng re-run thay vì block — correction rẻ, chờ đợi mới đắt;
+  - autonomy: repo đã vượt ngưỡng để Codex end-to-end một feature (validate state,
+    reproduce bug, quay video lỗi, fix, validate bằng cách drive app, quay video
+    fix, mở PR, phản hồi feedback, sửa build fail, escalate khi cần judgment,
+    merge) — nhưng *phụ thuộc nặng vào structure/tooling của repo này, chưa nên
+    giả định generalize nếu không đầu tư tương tự*;
+  - entropy và "garbage collection": Codex nhân bản cả pattern dở → drift; thay vì
+    dọn "AI slop" thủ công mỗi thứ Sáu (20% tuần, không scale), encode "golden
+    principle" + background task định kỳ quét deviation, cập nhật quality grade,
+    mở PR refactor nhỏ (review < 1 phút, automerge); tech debt như khoản vay lãi
+    cao, trả dần liên tục;
+  - frontier kế tiếp: thiết kế environment, feedback loop, và control system để
+    agent xây + bảo trì phần mềm phức tạp, tin cậy ở quy mô lớn; chưa rõ
+    coherence kiến trúc tiến hóa thế nào qua nhiều năm trong hệ thuần agent.
+
+Ghi chú ngày: bài mô tả commit đầu "late August 2025" + "five months later", và
+được InfoQ đưa tin tháng 2/2026, nên dùng 11/2/2026. Bản clipping nội bộ ghi
+`published: 2026-05-27` (nhiều khả năng là metadata clip sai); nếu cần con số
+chính thức, xác minh lại trên trang OpenAI.
 
 ### [S2] Anthropic
 
@@ -34,13 +86,21 @@ này hoặc không được đánh dấu rõ là diễn giải.
 - Ngày xuất bản: 26 tháng 11, 2025
 - URL: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
 - Dùng cho:
-  - failure mode của agent qua nhiều context window;
-  - initializer agent và coding agent;
-  - feature list dạng JSON với trạng thái pass/fail;
-  - tiến triển từng feature thay vì làm quá rộng;
-  - progress file, git commit, và `init.sh`;
-  - kiểm thử đầu-cuối bằng browser automation;
-  - vòng bắt đầu session: đọc progress, feature list, git log, setup, smoke test.
+  - failure mode của agent qua nhiều context window (như kỹ sư làm theo ca mà
+    không nhớ ca trước), cần externalize state;
+  - tách initializer agent (dựng `init.sh`, file progress, git commit đầu) khỏi
+    coding agent (làm tăng tiến từng phần, để lại code sạch mergeable);
+  - feature list dạng JSON (vài trăm feature) với category, mô tả kèm bước kiểm
+    chứng, và trường boolean `passes`; không được xóa/sửa test;
+  - tiến triển từng feature một thay vì làm quá rộng để tránh cạn context giữa
+    chừng;
+  - progress file, git commit mô tả rõ (cho phép revert/khôi phục), và `init.sh`
+    để khỏi tốn thời gian setup;
+  - kiểm thử đầu-cuối bằng browser automation (Puppeteer MCP), kiểm như người
+    dùng thay vì chỉ unit test/API;
+  - vòng bắt đầu session: `pwd`, đọc git log + progress, đọc feature list và chọn
+    feature ưu tiên cao chưa xong, chạy `init.sh`, smoke test, rồi mới code;
+  - hướng mở rộng: multi-agent chuyên cho test, QA, và cleanup.
 
 ### [S3] Anthropic
 
@@ -49,13 +109,22 @@ này hoặc không được đánh dấu rõ là diễn giải.
 - Ngày xuất bản: 19 tháng 12, 2024
 - URL: https://www.anthropic.com/engineering/building-effective-agents
 - Dùng cho:
-  - phân biệt workflow định tuyến sẵn và agent tự điều khiển process/tool;
-  - nguyên tắc bắt đầu bằng giải pháp đơn giản nhất;
-  - tradeoff giữa performance, latency, cost, và complexity;
-  - building block "augmented LLM" với retrieval, tool, và memory;
-  - workflow pattern như prompt chaining, routing, parallelization,
-    orchestrator-workers, evaluator-optimizer;
-  - thiết kế agent-computer interface và tool definition dễ dùng.
+  - phân biệt workflow (LLM + tool đi theo predefined code path) và agent (LLM tự
+    điều khiển process và tool usage);
+  - nguyên tắc bắt đầu bằng giải pháp đơn giản nhất, chỉ tăng complexity khi cần;
+    thường tối ưu single LLM call với retrieval + in-context example là đủ;
+  - tradeoff: agentic system đánh đổi latency và cost để có task performance tốt
+    hơn, phải cân nhắc khi nào đáng;
+  - building block "augmented LLM" với retrieval, tool, và memory, kèm interface
+    dễ dùng và tài liệu tốt;
+  - workflow pattern: prompt chaining, routing, parallelization (sectioning +
+    voting), orchestrator-workers, evaluator-optimizer, kèm khi nào dùng;
+  - agent như LLM dùng tool dựa trên feedback môi trường trong vòng lặp, cần
+    sandbox + guardrail + human oversight tại checkpoint;
+  - thiết kế agent-computer interface (ACI) như đầu tư ngang HCI: đặt mình vào vị
+    trí model, đặt tên tham số rõ, test nhiều input, áp dụng poka-yoke; ví dụ
+    SWE-bench dùng absolute filepath để loại lỗi đường dẫn tương đối;
+  - ba nguyên tắc lõi: simplicity, transparency, và tool documentation kỹ.
 
 ### [S4] Anthropic
 
@@ -64,58 +133,83 @@ này hoặc không được đánh dấu rõ là diễn giải.
 - Ngày xuất bản: 24 tháng 3, 2026
 - URL: https://www.anthropic.com/engineering/harness-design-long-running-apps
 - Dùng cho:
-  - vấn đề context anxiety và self-evaluation;
-  - tách generator khỏi evaluator;
-  - grading criteria để làm chất lượng chủ quan dễ chấm hơn;
-  - planner-generator-evaluator cho phát triển ứng dụng dài hạn;
-  - sprint contract giữa generator và evaluator;
-  - QA bằng Playwright qua UI, API, database state, và hành vi runtime;
-  - chi phí, độ trễ, và token cost của harness phức tạp;
-  - nguyên tắc xem lại harness khi model mới làm một số lớp orchestration không
-    còn load-bearing.
-
-### [S5] Google
-
-- Tiêu đề: "AutoHarness: Improving LLM Agents by Automatically Synthesizing a Code Harness" (Google DeepMind) và thực tiễn vận hành Agent/Evaluation Harness trên Google Cloud.
-- Tác giả: Google DeepMind & Google Cloud
-- Ngày xuất bản: 2024-2026
-- URL: https://arxiv.org/abs/2406.11252
+  - context anxiety (model "wrap up" sớm khi tưởng sắp hết context) và self-
+    evaluation bias (agent khen chính sản phẩm của mình dù chất lượng tầm
+    thường), nặng nhất với việc mang tính chủ quan;
+  - tách generator khỏi evaluator: tinh chỉnh một evaluator độc lập dễ hơn nhiều
+    so với bắt generator tự phê phán công việc của chính nó;
+  - grading criteria để làm chất lượng chủ quan dễ chấm hơn (ví dụ frontend:
+    design quality, originality, craft, functionality, nhấn mạnh design và
+    originality nơi model thường yếu);
+  - kiến trúc planner-generator-evaluator cho phát triển ứng dụng dài hạn;
+  - sprint contract: thỏa thuận về phạm vi và định nghĩa "done" trước khi
+    implement;
+  - QA bằng Playwright MCP qua UI, API, database state, và hành vi runtime (ví dụ
+    bắt lỗi route-matching FastAPI, lỗi đồng bộ state);
+  - chi phí/độ trễ/token của harness phức tạp như tradeoff thực (so sánh
+    single-agent ~20 phút/$9 cho ra sản phẩm hỏng vs full harness ~6 giờ/$200 cho
+    ra sản phẩm hoàn chỉnh; V2 ~3h50/$124.70);
+  - nguyên tắc "every component in a harness encodes an assumption about what the
+    model can't do on its own": khi Opus 4.6 xử lý long-context và planning tốt
+    hơn, sprint decomposition trở thành overhead và bị bỏ, giữ lại planner +
+    evaluator — harness phải được xem lại khi model mới xuất hiện.
+
+### [S5] Google DeepMind
+
+- Tiêu đề: "AutoHarness: improving LLM agents by automatically synthesizing a code harness"
+- Tác giả: Xinghua Lou, Miguel Lázaro-Gredilla, Antoine Dedieu, Carter Wendelken,
+  Wolfgang Lehrach, Kevin P. Murphy
+- Ngày xuất bản: 10 tháng 2, 2026
+- URL: https://arxiv.org/abs/2603.03329
 - Dùng cho:
-  - AutoHarness: Tự động tổng hợp lớp bọc thực thi (code harness/wrapper) bằng LLM để chặn hành động lỗi và cưỡng chế ràng buộc;
-  - Harness-as-Policy: Biên dịch chính sách quyết định thành code tĩnh để giảm chi phí/độ trễ runtime về 0;
-  - Trajectory Evaluation: Đánh giá vết chạy đầy đủ (gồm tool call, suy luận) thay vì chỉ chấm điểm kết quả tĩnh;
-  - LLM-as-a-Judge tự động & Meta-Evaluation (VeRO) để liên tục tối ưu cấu trúc của agent.
+  - vấn đề agent thường thử hành động không hợp lệ trong môi trường (ví dụ 78% số
+    ván thua của Gemini-2.5-Flash trong Kaggle GameArena cờ vua là do nước đi
+    không hợp lệ);
+  - AutoHarness: model tự tổng hợp lớp bọc thực thi (code harness/wrapper) bằng
+    một số ít vòng iterative code refinement dựa trên feedback từ môi trường, để
+    chặn hành động không hợp lệ trước khi chúng tác động tới môi trường;
+  - harness sinh tự động giúp model nhỏ hơn (Gemini-2.5-Flash) vượt model lớn hơn
+    (Gemini-2.5-Pro) — ngăn nước đi không hợp lệ qua 145 ván TextArena;
+  - code-as-policy: sinh toàn bộ policy thành code tĩnh để loại bỏ LLM call ở thời
+    điểm ra quyết định, giảm chi phí và độ trễ runtime; code-policy đạt average
+    reward cao hơn cả Gemini-2.5-Pro và GPT-5.2-High trên 16 game single-player.
 
 ## Bản đồ bằng chứng
 
 | Nhận định | Nguồn |
 | --- | --- |
 | Harness engineering chuyển trọng tâm kỹ sư từ viết code tay sang thiết kế môi trường, intent, và feedback loop. | [S1] |
-| Repository-local knowledge giúp agent truy cập quyết định, quy tắc, và trạng thái mà không phụ thuộc chat history. | [S1] |
-| `AGENTS.md` nên là bản đồ ngắn trỏ tới nguồn sự thật sâu hơn, không phải một manual khổng lồ. | [S1] |
-| Chọn dependency và abstraction nên tính đến việc agent có thể inspect, validate, và modify chúng trực tiếp; hành vi opaque ở upstream làm giảm leverage. | [S1] |
-| Agent cần application legibility: UI, log, metric, trace, và môi trường dev có thể quan sát được. | [S1] |
-| Repository knowledge nên theo progressive disclosure và có kiểm tra cơ học cho freshness/cross-link; doc-gardening định kỳ giúp giảm drift của source of truth. | [S1] |
-| Documentation đơn thuần không đủ; architecture và taste nên được cưỡng chế bằng lint, structural test, và custom rule. | [S1] |
-| Throughput cao làm entropy tích lũy nhanh, nên cleanup định kỳ là một phần của harness. | [S1] |
-| Agent dài hạn dễ mất context giữa các session và cần externalized state. | [S2] |
-| Feature list, progress file, git history, và `init.sh` giúp session mới phục hồi trạng thái. | [S2] |
-| Feature list dạng JSON giúp agent giữ trạng thái feature có cấu trúc và cập nhật pass/fail nhất quán qua nhiều session. | [S2] |
-| Git commit mô tả rõ và progress update không chỉ để audit; chúng còn tạo checkpoint để agent revert thay đổi xấu và khôi phục working state sạch hơn. | [S2] |
-| Làm từng feature và chỉ đánh dấu pass sau kiểm thử giúp giảm tuyên bố hoàn thành sớm. | [S2] |
-| Browser automation giúp agent phát hiện lỗi không thấy được từ code hoặc unit test đơn lẻ. | [S2] |
-| Agentic system nên bắt đầu bằng giải pháp đơn giản nhất và chỉ tăng complexity khi cần. | [S3] |
+| Khi agent gặp lỗi, phản xạ đúng là hỏi "thiếu capability nào và làm sao agent thấy + cưỡng chế được", không phải tự sửa tay. | [S1] |
+| Repository-local knowledge có cấu trúc (`docs/`) là system of record, giúp agent truy cập quyết định/quy tắc/trạng thái mà không phụ thuộc chat history và tránh lệch doc–implementation. | [S1] |
+| `AGENTS.md` nên là bản đồ ngắn (~100 dòng) trỏ tới nguồn sự thật sâu hơn, không phải manual khổng lồ một-file. | [S1] |
+| Kiến trúc phân lớp với dependency chỉ đi tiến (`Types → Config → Repo → Service → Runtime → UI`) là ràng buộc cho phép tốc độ mà không bị architectural drift. | [S1] |
+| Chọn dependency và abstraction nên tính đến việc agent có thể inspect, validate, và modify trực tiếp; hành vi opaque ở upstream làm giảm leverage. | [S1] |
+| Agent cần application legibility: log, metric, span/trace để giám sát hiệu năng và tái hiện bug qua môi trường dev cô lập. | [S1] |
+| Repository knowledge nên theo progressive disclosure và có kiểm tra cơ học cho freshness/cross-link (linter + CI) để giảm drift. | [S1] |
+| Documentation đơn thuần không đủ; architecture và taste nên được cưỡng chế bằng custom linter, structural test, và mechanical rule. | [S1] |
+| Review có thể đẩy gần hết sang agent-to-agent qua vòng lặp tự-review + xin agent review tới khi reviewer hài lòng; human review không bắt buộc. | [S1] |
+| Throughput cao đổi merge philosophy: merge gate tối thiểu, PR ngắn hạn, test flake re-run thay vì block — correction rẻ, chờ đợi đắt. | [S1] |
+| Throughput cao làm entropy tích lũy nhanh; encode "golden principle" + background task định kỳ mở PR refactor nhỏ (automerge) thay cho dọn slop thủ công là một phần của harness. | [S1] |
+| Mức autonomy end-to-end của agent phụ thuộc nặng vào structure/tooling cụ thể của repo, không nên giả định generalize nếu chưa đầu tư tương đương. | [S1] |
+| Agent dài hạn dễ mất context giữa các session (như làm theo ca không nhớ ca trước) và cần externalized state. | [S2] |
+| Tách initializer agent (dựng `init.sh`, progress, git) khỏi coding agent (làm tăng tiến, để lại code mergeable) giúp session mới phục hồi trạng thái. | [S2] |
+| Feature list dạng JSON với category, bước kiểm chứng, và trường `passes` giữ trạng thái feature có cấu trúc và nhất quán qua nhiều session; không được xóa/sửa test. | [S2] |
+| Git commit mô tả rõ và progress update tạo checkpoint để agent revert thay đổi xấu và khôi phục working state sạch. | [S2] |
+| Làm từng feature và chỉ đánh dấu pass sau kiểm thử đầu-cuối giúp giảm tuyên bố hoàn thành sớm. | [S2] |
+| Browser automation (Puppeteer MCP) giúp agent phát hiện lỗi không thấy được từ code hoặc unit test đơn lẻ. | [S2] |
+| Agentic system nên bắt đầu bằng giải pháp đơn giản nhất và chỉ tăng complexity khi cần; thường single LLM call + retrieval/example là đủ. | [S3] |
 | Workflow phù hợp với task có đường đi định sẵn; agent phù hợp khi cần model tự quyết định tool/process. | [S3] |
-| Tool nên được thiết kế như agent-computer interface với mô tả, tham số, ranh giới, và ví dụ rõ. | [S3] |
+| Agentic system đánh đổi latency và cost để lấy task performance, phải cân nhắc khi nào đáng. | [S3] |
+| Tool nên được thiết kế như agent-computer interface với mô tả, tham số, ranh giới, ví dụ rõ, và áp dụng poka-yoke để chống lạm dụng. | [S3] |
 | Generator tự đánh giá thường quá tích cực; evaluator riêng dễ được chỉnh thành hoài nghi hơn. | [S4] |
-| Sprint contract giúp generator và evaluator đồng thuận về phạm vi, tiêu chí done, và phương thức QA. | [S4] |
-| Context reset có thể là một phần chủ đích của harness; nếu state handoff đủ tốt, reset giúp giữ model bám task thay vì trượt theo context anxiety. | [S4] |
+| Grading criteria rõ (vd design quality, originality, craft, functionality) làm chất lượng chủ quan dễ chấm hơn. | [S4] |
+| Sprint contract giúp generator và evaluator đồng thuận về phạm vi, tiêu chí done, và phương thức QA trước khi implement. | [S4] |
+| QA bằng Playwright qua UI, API, database state, và hành vi runtime bắt được lỗi mà self-eval bỏ sót. | [S4] |
 | Harness phức tạp có thể tốn nhiều giờ và token, nên phải được xem là tradeoff thay vì mặc định. | [S4] |
-| Khi model mới xuất hiện, nên xem lại và loại bỏ các phần harness không còn tạo giá trị. | [S4] |
-| Thay vì tự viết thủ công mọi ràng buộc, mô hình (như Gemini Flash) có thể tự động tổng hợp lớp bọc thực thi (AutoHarness) bằng code để lọc các hành động lỗi. | [S5] |
-| Biên dịch chính sách quyết định thành code tĩnh (Harness-as-Policy) giúp loại bỏ việc gọi mô hình ở runtime, tối ưu hóa chi phí và độ trễ. | [S5] |
-| Đánh giá agent dài hạn cần dựa trên vết chạy đầy đủ (Trajectory Evaluation) bao gồm cả chuỗi gọi tool và suy luận, thay vì chỉ so sánh kết quả đầu ra tĩnh. | [S5] |
-| LLM-as-a-Judge tự động giúp đo lường độ an toàn và hiệu năng của agent liên tục, và Meta-Evaluation (VeRO) tối ưu hóa cấu trúc của harness dựa trên phản hồi. | [S5] |
+| Mỗi thành phần harness mã hóa một giả định về thứ model chưa tự làm được; khi model mới mạnh hơn, nên xem lại và loại bỏ phần không còn tạo giá trị (vd bỏ sprint khi Opus 4.6 tự planning tốt). | [S4] |
+| Agent thường thử hành động không hợp lệ trong môi trường (vd 78% ván thua của Gemini-2.5-Flash do nước đi sai luật). | [S5] |
+| Thay vì tự viết thủ công mọi ràng buộc, model có thể tự tổng hợp lớp bọc thực thi (AutoHarness) bằng iterative code refinement để lọc hành động không hợp lệ, giúp model nhỏ vượt model lớn. | [S5] |
+| Sinh toàn bộ policy thành code tĩnh (code-as-policy) loại bỏ LLM call lúc ra quyết định, tối ưu chi phí/độ trễ và có thể vượt cả model lớn trên các môi trường single-player. | [S5] |
 
 ## Chính sách citation
 

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "codex-harness-engineering",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Codex harness engineering docs and installable agent skills.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bonnguyenitc/codex-harness-engineering.git"
+  },
   "keywords": [
     "codex",
     "harness-engineering",
@@ -19,14 +23,15 @@
     "README.md",
     "docs",
     "scripts",
-    "skills"
+    "skills",
+    "templates"
   ],
   "scripts": {
     "test": "node --test tests/*.test.mjs",
     "verify": "node scripts/verify-harness.mjs && npm test",
     "pack:dry": "npm pack --dry-run",
     "release": "./scripts/publish.sh",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm run verify"
   },
   "engines": {
     "node": ">=18.17"
@@ -34,5 +39,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "UNLICENSED"
+  "license": "MIT"
 }

package/scripts/install-skills.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { realpathSync } from "node:fs";
-import { access, cp, mkdir, rm } from "node:fs/promises";
+import { access, chmod, cp, mkdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -12,6 +12,18 @@ export const SKILL_NAMES = [
   "acceptance-contract",
   "cleanup-harness",
   "creator-harness",
+  "lessons-harness",
+];
+
+export const HARNESS_FILES = [
+  "AGENTS.md",
+  "progress.md",
+  "feature_list.json",
+  "lessons.md",
+  "memory/README.md",
+  "init.sh",
+  "verify-state.mjs",
+  "rotate-state.mjs",
 ];
 
 async function exists(filePath) {
@@ -33,49 +45,91 @@ export async function installSkills({
   packageRoot = PACKAGE_ROOT,
   projectRoot = process.cwd(),
   force = false,
+  harness = false,
+  team = false,
 } = {}) {
   const sourceRoot = path.join(packageRoot, "skills");
   const targetRoot = path.join(projectRoot, ".agents", "skills");
   const docsSource = path.join(packageRoot, "docs", "harness-engineering");
   const docsTarget = path.join(projectRoot, "docs", "harness-engineering");
+  const harnessSource = path.join(packageRoot, "templates", "harness");
+  const teamSource = path.join(packageRoot, "templates", "team");
+  const teamTarget = path.join(projectRoot, "team");
+  const scaffoldHarness = harness || team;
   const installed = [];
-
-  await mkdir(targetRoot, { recursive: true });
+  const scaffolded = [];
+  const copies = [];
 
   for (const skillName of SKILL_NAMES) {
     const source = path.join(sourceRoot, skillName);
     const target = path.join(targetRoot, skillName);
 
     if (path.resolve(source) !== path.resolve(target)) {
-      await assertCanWrite(target, force);
-      await rm(target, { recursive: true, force: true });
-      await cp(source, target, { recursive: true, force: true });
+      copies.push({ source, target });
     }
     installed.push(skillName);
   }
 
   if (path.resolve(docsSource) !== path.resolve(docsTarget)) {
-    await assertCanWrite(docsTarget, force);
-    await rm(docsTarget, { recursive: true, force: true });
-    await cp(docsSource, docsTarget, { recursive: true, force: true });
+    copies.push({ source: docsSource, target: docsTarget });
+  }
+
+  if (scaffoldHarness) {
+    for (const fileName of HARNESS_FILES) {
+      const source = path.join(harnessSource, fileName);
+      const target = path.join(projectRoot, fileName);
+
+      if (path.resolve(source) !== path.resolve(target)) {
+        copies.push({ source, target });
+        scaffolded.push(fileName);
+      }
+    }
+  }
+
+  if (team && path.resolve(teamSource) !== path.resolve(teamTarget)) {
+    copies.push({ source: teamSource, target: teamTarget });
+    scaffolded.push("team/");
   }
 
-  return { targetRoot, docsTarget, installed };
+  // Check every target before copying anything so a conflict cannot leave a
+  // partial install behind.
+  for (const { target } of copies) {
+    await assertCanWrite(target, force);
+  }
+
+  await mkdir(targetRoot, { recursive: true });
+
+  for (const { source, target } of copies) {
+    await rm(target, { recursive: true, force: true });
+    await cp(source, target, { recursive: true, force: true });
+  }
+
+  if (scaffolded.includes("init.sh")) {
+    await chmod(path.join(projectRoot, "init.sh"), 0o755);
+  }
+
+  return { targetRoot, docsTarget, installed, scaffolded };
 }
 
 export function parseArgs(args) {
   const [command, ...flags] = args;
 
   if (command !== "init") {
-    throw new Error("Usage: codex-harness-engineering init [--force]");
+    throw new Error("Usage: codex-harness-engineering init [--force] [--team]");
   }
 
-  const unknownFlag = flags.find((flag) => flag !== "--force");
+  const knownFlags = ["--force", "--harness", "--starter-kit", "--team"];
+  const unknownFlag = flags.find((flag) => !knownFlags.includes(flag));
   if (unknownFlag) {
     throw new Error(`Unknown option: ${unknownFlag}`);
   }
 
-  return { command, force: flags.includes("--force") };
+  return {
+    command,
+    force: flags.includes("--force"),
+    harness: true,
+    team: flags.includes("--team"),
+  };
 }
 
 function isDirectRun() {
@@ -89,14 +143,18 @@ function isDirectRun() {
 
 if (isDirectRun()) {
   try {
-    const { force } = parseArgs(process.argv.slice(2));
-    const { targetRoot, docsTarget, installed } = await installSkills({ force });
+    const { force, harness, team } = parseArgs(process.argv.slice(2));
+    const { targetRoot, docsTarget, installed, scaffolded } = await installSkills({ force, harness, team });
 
     console.log(`Installed ${installed.length} skills to ${targetRoot}`);
     for (const skillName of installed) {
       console.log(`- ${skillName}`);
     }
     console.log(`Copied docs to ${docsTarget}`);
+    if (scaffolded.length > 0) {
+      console.log(`Scaffolded harness files: ${scaffolded.join(", ")}`);
+      console.log("Next: edit init.sh and the Commands section of AGENTS.md.");
+    }
   } catch (error) {
     console.error(error instanceof Error ? error.message : error);
     process.exitCode = 1;

package/scripts/publish.sh

@@ -95,8 +95,8 @@ fi
 echo "New version: $NEW_VERSION"
 echo ""
 
-echo "Running tests..."
-npm test
+echo "Running harness verification and tests..."
+npm run verify
 
 echo ""
 echo "Checking package contents..."

package/scripts/verify-harness.mjs

@@ -11,6 +11,8 @@ const REQUIRED_FILES = [
   "README.md",
   "progress.md",
   "feature_list.json",
+  "lessons.md",
+  "memory/README.md",
   "init.sh",
   "docs/harness-engineering/index.md",
   "docs/harness-engineering/research-note.md",
@@ -19,13 +21,18 @@ const REQUIRED_FILES = [
   "skills/creator-harness/SKILL.md",
   "skills/acceptance-contract/SKILL.md",
   "skills/cleanup-harness/SKILL.md",
+  "skills/lessons-harness/SKILL.md",
 ];
 const README_MAPPED_FILES = REQUIRED_FILES.filter(
   (relativePath) => relativePath !== "AGENTS.md" && relativePath !== "README.md"
 );
 const STATE_FILES = ["feature_list.json", "progress.md"];
+const LINE_BUDGETS = {
+  "progress.md": 400,
+  "lessons.md": 400,
+};
 const BEHAVIOR_CHANGE_PATTERNS = [
-  /^(scripts|tests|skills)\//,
+  /^(scripts|tests|skills|templates)\//,
   /^package(?:-lock)?\.json$/,
   /^init\.sh$/,
   /^AGENTS\.md$/,
@@ -40,7 +47,7 @@ async function exists(filePath) {
   }
 }
 
-async function markdownFiles(directory, relativeRoot) {
+async function listFiles(directory, relativeRoot, matches) {
   if (!await exists(directory)) {
     return [];
   }
@@ -53,8 +60,8 @@ async function markdownFiles(directory, relativeRoot) {
     const relativePath = path.join(relativeRoot, entry.name);
 
     if (entry.isDirectory()) {
-      found.push(...await markdownFiles(absolutePath, relativePath));
-    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      found.push(...await listFiles(absolutePath, relativePath, matches));
+    } else if (entry.isFile() && entry.name !== ".DS_Store" && matches(entry.name)) {
       found.push(relativePath);
     }
   }
@@ -62,6 +69,43 @@ async function markdownFiles(directory, relativeRoot) {
   return found;
 }
 
+function markdownFiles(directory, relativeRoot) {
+  return listFiles(directory, relativeRoot, (name) => name.endsWith(".md"));
+}
+
+async function skillsMirrorErrors(root) {
+  const mirrorRoot = path.join(root, ".agents", "skills");
+  if (!await exists(mirrorRoot)) {
+    return [];
+  }
+
+  const errors = [];
+  const sourceFiles = await listFiles(path.join(root, "skills"), "", () => true);
+  const mirrorFiles = await listFiles(mirrorRoot, "", () => true);
+
+  for (const relativePath of sourceFiles) {
+    const mirrorPath = path.join(mirrorRoot, relativePath);
+    if (!await exists(mirrorPath)) {
+      errors.push(`.agents/skills/${relativePath}: mirror copy of skills/${relativePath} is missing`);
+      continue;
+    }
+
+    const source = await readFile(path.join(root, "skills", relativePath), "utf8");
+    const mirror = await readFile(mirrorPath, "utf8");
+    if (source !== mirror) {
+      errors.push(`.agents/skills/${relativePath}: mirror copy is out of sync with skills/${relativePath}`);
+    }
+  }
+
+  for (const relativePath of mirrorFiles) {
+    if (!sourceFiles.includes(relativePath)) {
+      errors.push(`.agents/skills/${relativePath}: has no source file under skills/`);
+    }
+  }
+
+  return errors;
+}
+
 function changesHarnessBehavior(relativePath) {
   return BEHAVIOR_CHANGE_PATTERNS.some((pattern) => pattern.test(relativePath));
 }
@@ -128,6 +172,19 @@ export async function verifyHarness(root = PACKAGE_ROOT, { changedFiles = [] } =
     }
   }
 
+  errors.push(...await skillsMirrorErrors(root));
+
+  for (const [relativePath, budget] of Object.entries(LINE_BUDGETS)) {
+    if (await exists(path.join(root, relativePath))) {
+      const lineCount = (await readFile(path.join(root, relativePath), "utf8")).split("\n").length;
+      if (lineCount > budget) {
+        errors.push(
+          `${relativePath}: ${lineCount} lines exceeds the ${budget}-line budget; archive older entries with node templates/harness/rotate-state.mjs .`
+        );
+      }
+    }
+  }
+
   const behaviorChanges = changedFiles.filter(changesHarnessBehavior);
   if (behaviorChanges.length > 0) {
     for (const stateFile of STATE_FILES) {