codex-harness-engineering 0.1.4 → 0.1.6

package/skills/creator-harness/references/harness-artifacts.md

@@ -1,18 +1,18 @@
-# Harness Artifact Templates
+# Mẫu Artifact Harness
 
-Use these templates selectively. Do not create every artifact by default.
+Dùng các mẫu này một cách chọn lọc. Đừng tạo mọi artifact theo mặc định.
 
-Each artifact must answer at least one question:
+Mỗi artifact phải trả lời ít nhất một câu hỏi:
 
-- What should the agent know?
-- What state survives context loss?
-- What can the agent observe?
-- How does the agent verify work?
-- What constraint is mechanically enforced?
+- Agent cần biết gì?
+- State nào sống sót qua mất context?
+- Agent quan sát được gì?
+- Agent verify công việc thế nào?
+- Ràng buộc nào được cưỡng chế cơ học?
 
-## Contents
+## Mục lục
 
-- Minimal Repository Harness
+- Harness repository tối thiểu
 - AGENTS.md
 - progress.md
 - feature_list.json
@@ -21,11 +21,12 @@ Each artifact must answer at least one question:
 - Acceptance Contract
 - Sprint Contract
 - Evaluator Notes
+- Legibility Map
 - Cleanup Task
 
-## Minimal Repository Harness
+## Harness repository tối thiểu
 
-Start here unless a named failure mode requires more.
+Bắt đầu từ đây trừ khi một failure mode có tên đòi hỏi nhiều hơn.
 
 ```text
 AGENTS.md
@@ -33,11 +34,11 @@ README.md
 progress.md
 feature_list.json
 init.sh
-Makefile or task runner
-tests/ or smoke test
+Makefile hoặc task runner
+tests/ hoặc smoke test
 ```
 
-Optional only when needed:
+Chỉ thêm khi cần:
 
 ```text
 docs/architecture.md
@@ -99,8 +100,8 @@ cleanup.md
 - ...
 ```
 
-Keep entries short and recoverable. Prefer file paths, command names, failing
-test names, and artifact paths over vague prose.
+Giữ mỗi entry ngắn và khôi phục được. Ưu tiên đường dẫn file, tên lệnh, tên test
+fail, và đường dẫn artifact hơn là văn xuôi mơ hồ.
 
 ## feature_list.json
 
@@ -124,8 +125,8 @@ test names, and artifact paths over vague prose.
 ]
 ```
 
-Use status values consistently: `not_started`, `in_progress`, `blocked`,
-`verified`. Only set `verified` after listed checks pass.
+Dùng giá trị `status` nhất quán: `not_started`, `in_progress`, `blocked`,
+`verified`. Chỉ đặt `verified` sau khi các kiểm tra đã liệt kê pass.
 
 ## init.sh
 
@@ -161,22 +162,22 @@ smoke:
 verify: lint test build smoke
 ```
 
-Keep command names stable. Agent instructions should point to these targets
-instead of repeating long command lines across files.
+Giữ tên lệnh ổn định. Hướng dẫn cho agent nên trỏ tới các target này thay vì lặp
+lại dòng lệnh dài qua nhiều file.
 
 ## Acceptance Contract
 
-Use this for a small bug or feature when planner/evaluator would be too much.
+Dùng cho một bug hoặc feature nhỏ khi planner/evaluator là quá mức.
 
 ```markdown
 # Acceptance Contract
 
-## Scope
+## Phạm vi
 - Feature/fix:
-- User-visible behavior:
-- Likely files:
+- Hành vi nhìn thấy phía người dùng:
+- File có khả năng đụng đến:
 
-## Acceptance Criteria
+## Tiêu chí nghiệm thu
 - [ ] ...
 - [ ] ...
 
@@ -186,28 +187,28 @@ Use this for a small bug or feature when planner/evaluator would be too much.
 - Browser/API:
 - Log/metric/trace:
 
-## Out of Scope
+## Ngoài phạm vi
 - ...
 ```
 
 ## Sprint Contract
 
-Use this when work spans multiple files, runtime behavior, or subjective quality.
+Dùng khi công việc trải qua nhiều file, hành vi runtime, hoặc chất lượng chủ quan.
 
 ```markdown
 # Sprint Contract
 
-## Scope
+## Phạm vi
 - Feature:
 - User path:
 - API/data path:
-- Likely files/modules:
+- File/module có khả năng đụng đến:
 
-## Done Means
+## Done nghĩa là
 - [ ] User can ...
-- [ ] API or data reflects ...
-- [ ] Error state handles ...
-- [ ] No regression in ...
+- [ ] API hoặc data phản ánh ...
+- [ ] Trạng thái lỗi xử lý ...
+- [ ] Không regression ở ...
 
 ## Verification
 - Unit:
@@ -215,56 +216,56 @@ Use this when work spans multiple files, runtime behavior, or subjective quality
 - Browser/API:
 - Log/metric/trace:
 
-## Evaluator Focus
-- Runtime behavior:
-- Negative cases:
-- UX or quality concerns:
+## Trọng tâm Evaluator
+- Hành vi runtime:
+- Ca âm (negative cases):
+- Lo ngại về UX hoặc chất lượng:
 
-## Out of Scope
+## Ngoài phạm vi
 - ...
 ```
 
-If the sprint contract becomes longer than the work, split the work or fall back
-to a smaller acceptance contract.
+Nếu sprint contract dài hơn cả phần việc, hãy chia nhỏ công việc hoặc lùi về một
+acceptance contract nhỏ hơn.
 
 ## Evaluator Notes
 
-Use this when generator self-review is not enough.
+Dùng khi generator tự review chưa đủ.
 
 ```markdown
 # Evaluator Notes
 
 ## Contract
 - Sprint:
-- Expected behavior:
+- Hành vi kỳ vọng:
 
-## Checks Run
-- Command/check:
-- Result:
+## Kiểm tra đã chạy
+- Lệnh/kiểm tra:
+- Kết quả:
 - Artifact:
 
-## Findings
+## Phát hiện
 - [ ] P0/P1/P2:
-  - Evidence:
+  - Bằng chứng:
   - Repro:
-  - Suggested next step:
+  - Bước tiếp theo đề xuất:
 
-## Verdict
+## Phán quyết
 - pass/fail:
-- Reason:
+- Lý do:
 ```
 
-Evaluator feedback should cite observed evidence: screenshots, DOM state, API
-response, database state, logs, traces, or command output.
+Feedback của evaluator nên dẫn bằng chứng quan sát được: screenshot, DOM state,
+API response, database state, log, trace, hoặc output của lệnh.
 
 ## Legibility Map
 
-Use this when the agent cannot see enough runtime behavior.
+Dùng khi agent không nhìn thấy đủ hành vi runtime.
 
 ```markdown
 # Legibility Map
 
-| Area | Signal | How to collect | Owner/check |
+| Khu vực | Tín hiệu | Cách thu thập | Owner/kiểm tra |
 | --- | --- | --- | --- |
 | UI | Screenshot/DOM |  |  |
 | API | Request/response |  |  |
@@ -276,20 +277,20 @@ Use this when the agent cannot see enough runtime behavior.
 
 ## Cleanup Task
 
-Use this when agent throughput creates repeated drift.
+Dùng khi throughput của agent tạo ra drift lặp lại.
 
 ```markdown
 # Cleanup Task
 
 ## Trigger
-- Repeated pattern:
-- Evidence:
+- Pattern lặp lại:
+- Bằng chứng:
 
-## Scope
-- Include:
-- Exclude:
+## Phạm vi
+- Bao gồm:
+- Loại trừ:
 
-## Acceptance Criteria
+## Tiêu chí nghiệm thu
 - [ ] ...
 
 ## Verification

package/skills/lessons-harness/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: lessons-harness
+description: Dùng khi một gate fail, regression, defect review, hoặc lỗi sửa đi sửa lại cần trở thành bài học bền vững — ghi lại lỗi, rút ra quy tắc, và đẩy các quy tắc lặp lại thành guardrail cơ học.
+---
+
+# Lessons Harness
+
+## Điều kiện kích hoạt
+
+Ghi một bài học vào `lessons.md` khi:
+
+- một verify gate, test, hoặc smoke check fail vì lý do do agent gây ra;
+- một regression xuất hiện ở hành vi trước đây vốn chạy đúng;
+- review hoặc evaluator bắt được một lớp defect do agent tạo ra;
+- cùng một cách sửa hoặc workaround được áp dụng lần thứ hai;
+- một giả định sai về repo, một tool, hoặc một nguồn còn sống sót qua session
+  đã tạo ra nó.
+
+Không ghi các fail red-green thường thấy trong TDD bình thường, hoặc flake môi
+trường nằm ngoài tầm kiểm soát của agent.
+
+## Quy trình
+
+1. Viết bài học khi bối cảnh lỗi còn tươi. Mỗi mục một bài học: mistake, root
+   cause, rule, status.
+2. Giữ rule mang tính vận hành: một hành vi hoặc kiểm tra cụ thể cho lần sau,
+   không phải ý định mơ hồ.
+3. Tìm trong `lessons.md` và `memory/lessons/` cùng một root cause trước khi
+   thêm bản gần-trùng; nếu đã có, rule là lặp lại.
+4. Đẩy một rule lặp lại vào dạng cơ học nhỏ nhất giữ được nó [S1], [S3]:
+   - quy tắc hành vi bền vững → một dòng rule trong `AGENTS.md`;
+   - invariant về cấu trúc hoặc style → một lint hoặc structural test;
+   - invariant về state hoặc quy trình → mở rộng verify gate;
+   - policy phức tạp → một code wrapper tổng hợp chặn hành động không hợp lệ
+     trước khi thực thi [S5].
+5. Đổi dòng status của bài học thành `Status: promoted: <ở đâu>` rồi chạy
+   `node rotate-state.mjs` để các bài học đã promote chuyển sang
+   `memory/lessons/` và file nóng giữ nhỏ.
+6. Ghi lần promote vào `progress.md` như mọi thay đổi hành vi khác.
+
+## Định dạng một bài học
+
+Mỗi mục trong `lessons.md` theo dạng sau (heading có ngày, bốn trường):
+
+- Mistake: điều gì sai và quan sát ở đâu.
+- Root cause: vì sao xảy ra, không chỉ là cái gì hỏng.
+- Rule: hành vi hoặc kiểm tra ngăn nó lặp lại lần sau.
+- Status: `pending`, hoặc `promoted: <vị trí rule hoặc gate>`.
+
+## Hướng dẫn promote
+
+- Ưu tiên can thiệp nhỏ nhất loại bỏ được failure mode [S3].
+- Một rule đã promote phải bảo vệ một invariant cụ thể; đừng thêm quy tắc rộng
+  mà không ràng buộc gì.
+- Khi verify gate có thêm một kiểm tra, thêm một regression test cho chính kiểm
+  tra đó.
+- Bài học pending là state nóng agent đọc mỗi session; bài học đã promote là
+  lịch sử nguội. Giữ file nóng trong ngân sách dòng của nó.
+
+## Ánh xạ nguồn
+
+- Tri thức cục bộ trong repo sống lâu hơn session; lịch sử chat thì không [S1].
+- Agent chạy dài cần state được externalize để khôi phục và cải thiện qua các
+  session [S2].
+- Giữ mỗi can thiệp đơn giản đúng mức mà failure mode cho phép [S3].
+- Chuyển phán đoán lặp lại thành kiểm tra cơ học mạnh hơn văn xuôi [S1].
+- AutoHarness cho thấy policy có thể được tổng hợp thành code wrapper tĩnh lọc
+  hành động không hợp lệ trước khi thực thi [S5].

package/skills/lessons-harness/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Lessons Harness"
+  short_description: "Biến lỗi thành quy tắc và gate"
+  default_prompt: "Dùng $lessons-harness để ghi một lỗi thành bài học kèm root cause và rule, rồi đẩy các rule lặp lại thành guardrail cơ học."

package/templates/harness/AGENTS.md

@@ -0,0 +1,77 @@
+# Agent Instructions
+
+Codex reads this file at the start of every session. Keep it a short map; the
+deeper source of truth lives in the files it points to, not in chat history.
+
+## Start Here
+
+1. Read `README.md`.
+2. Read the latest entries in `progress.md` to recover what the previous
+   session did.
+3. Check `feature_list.json` for the current capability state.
+4. Read `lessons.md` for pending mistakes and rules from prior sessions.
+5. Run `./init.sh` to set up and smoke-test before editing anything.
+6. Review recent git history to see what the last session changed.
+
+## Skills
+
+Installed under `.agents/skills/`. Invoke with `$skill-name`:
+
+- `$acceptance-contract` — before implementing: lock scope, done criteria, and
+  verification commands.
+- `$creator-harness` — when this harness is missing a layer for a named
+  failure mode (lost context, invisible runtime, optimistic self-review).
+- `$cleanup-harness` — when repeated drift, duplicate helpers, or doc rot
+  appears across sessions.
+- `$lessons-harness` — when a verify gate, test, or review catches a mistake;
+  log it in `lessons.md` and promote recurring rules into guardrails.
+
+## Memory Layout
+
+Hot files are read every session; cold files are searched only when history is
+needed. Do not let hot files grow unbounded.
+
+- `progress.md` — hot: recent session log (latest entries only).
+- `feature_list.json` — hot: active capabilities only.
+- `lessons.md` — hot: pending mistakes and the rules derived from them.
+- `memory/README.md` — cold: archive contract for rotated state.
+- `memory/progress/<YYYY-MM>.md` — cold: archived progress entries by month.
+- `memory/features-archive.json` — cold: verified capabilities with evidence.
+- `memory/lessons/<YYYY-MM>.md` — cold: promoted lessons by month.
+- Rotate with `node rotate-state.mjs`; the state gate fails when
+  `progress.md` or `lessons.md` exceeds its line budget.
+
+## Commands
+
+<!-- Fill these in for your project. Codex reads this table before guessing. -->
+
+- Setup:
+- Test:
+- Lint:
+- Build:
+- Smoke: `./init.sh`
+- State gate: `node verify-state.mjs`
+- Memory rotate: `node rotate-state.mjs`
+
+## Rules
+
+- Work on one feature from `feature_list.json` at a time; do not widen scope
+  mid-session.
+- If `team/` exists, multi-role work follows `team/workflow.md`: one session
+  plays one role (planner, implementer, or evaluator) and `node
+  team/verify-team.mjs` must pass alongside the state gate.
+- Keep changes scoped to the requested feature or fix.
+- Update a feature status in `feature_list.json` only after its `verify`
+  commands pass.
+- When a task changes behavior, guardrails, packages, scripts, or tests, update
+  `feature_list.json` and `progress.md` before finishing — even for small
+  tasks. The latest progress entry must list the changed files.
+- Run `node verify-state.mjs` before committing; it mechanically enforces the
+  rule above and must pass.
+- When a verify gate, test, or review catches a mistake the agent caused, log
+  it in `lessons.md` via `$lessons-harness` before finishing the session. If
+  the same rule appears twice, promote it into this file or a verify gate.
+- End every session with a descriptive commit and a `progress.md` entry. The
+  commit is the recovery point the next Codex session reverts to if a change
+  goes bad.
+- Do not refactor unrelated code.

package/templates/harness/feature_list.json

@@ -0,0 +1,16 @@
+[
+  {
+    "id": "F001",
+    "title": "Replace me with the first real capability",
+    "status": "not_started",
+    "acceptance": [
+      "User can ...",
+      "System rejects ...",
+      "Regression check passes ..."
+    ],
+    "verify": [
+      "./init.sh"
+    ],
+    "evidence": []
+  }
+]

package/templates/harness/init.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+# Keep this script idempotent: a brand-new session runs it first, before any
+# edit. It should set up the environment and run the cheapest smoke test.
+#
+# Replace the lines below with your project's real commands, for example:
+#   npm ci && npm test
+#   make setup && make smoke
+
+echo "init.sh is not configured yet." >&2
+echo "Edit init.sh to run this project's setup and cheapest smoke test." >&2
+exit 1

package/templates/harness/lessons.md

@@ -0,0 +1,18 @@
+# Lessons
+
+Mistakes this project has learned from, externalized so the next session does
+not repeat them. Log a lesson when a gate or test fails for an agent-caused
+reason, a regression appears, review catches an agent-made defect, or the same
+correction is applied twice. See `$lessons-harness` for the full workflow.
+
+Each lesson is one dated `## YYYY-MM-DD - Title` entry with four fields:
+`- Mistake:` what went wrong and where it was observed; `- Root cause:` why it
+happened; `- Rule:` the concrete behavior or check that prevents it next time;
+`- Status: pending` until the rule is promoted.
+
+When the same rule appears in two or more lessons, promote it into `AGENTS.md`
+or a mechanical gate, change the line to `- Status: promoted: <where>`, and run
+`node rotate-state.mjs`. Promoted lessons are archived; pending lessons stay
+hot and are read at the start of every session.
+
+Promoted lessons: see `memory/lessons/`.

package/templates/harness/memory/README.md

@@ -0,0 +1,22 @@
+# Memory Archive
+
+Cold storage for archived harness state.
+
+Hot files live at the repository root and are read every session:
+
+- `progress.md`
+- `feature_list.json`
+- `lessons.md`
+
+Rotate hot state with `node rotate-state.mjs` when the hot files approach their
+budget or when verified features / promoted lessons should move out of the hot
+set.
+
+Cold archive layout:
+
+- `memory/progress/<YYYY-MM>.md`
+- `memory/features-archive.json`
+- `memory/lessons/<YYYY-MM>.md`
+
+Do not put live task state here. This file is the contract for the cold archive
+layout and recovery path.

package/templates/harness/progress.md

@@ -0,0 +1,33 @@
+# Progress
+
+Keep entries short and recoverable. Prefer file paths, command names, failing
+test names, and artifact paths over vague prose. Newest entry goes last.
+
+## YYYY-MM-DD - Harness bootstrap
+
+### Context
+
+- Task: Bootstrap the repository harness.
+- Current branch:
+- Relevant files: `AGENTS.md`, `progress.md`, `feature_list.json`,
+  `memory/README.md`, `init.sh`, `verify-state.mjs`, `rotate-state.mjs`.
+
+### Done
+
+- Installed the minimal harness scaffold.
+
+### Verification
+
+- Command: `./init.sh`
+- Result: <!-- record the real result; do not mark pass without running it -->
+- Command: `node verify-state.mjs`
+- Result: <!-- record the real result -->
+
+### Open Issues
+
+- `init.sh` still needs the project's real setup and smoke commands.
+
+### Next
+
+- Fill in the Commands section of `AGENTS.md`.
+- Replace the placeholder feature in `feature_list.json` with real capabilities.

package/templates/harness/rotate-state.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Rotates harness memory so the hot state files stay small enough for an
+// agent to read at the start of every session.
+//
+// - progress.md keeps the latest KEEP_ENTRIES entries; older entries move to
+//   memory/progress/<YYYY-MM>.md grouped by entry month.
+// - feature_list.json keeps non-verified features; verified features move to
+//   memory/features-archive.json with their evidence.
+// - lessons.md keeps pending lessons; promoted lessons move to
+//   memory/lessons/<YYYY-MM>.md grouped by entry month.
+//
+// Run: node rotate-state.mjs [root]
+// The state gate (verify-state.mjs) reminds you when progress.md grows past
+// its line budget.
+
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = process.argv[2]
+  ? path.resolve(process.argv[2])
+  : path.dirname(fileURLToPath(import.meta.url));
+const KEEP_ENTRIES = 5;
+
+function splitEntries(progress) {
+  const lines = progress.split("\n");
+  const starts = [];
+  lines.forEach((line, index) => {
+    if (line.startsWith("## ")) {
+      starts.push(index);
+    }
+  });
+
+  const headerEnd = starts.length > 0 ? starts[0] : lines.length;
+  const header = lines.slice(0, headerEnd).join("\n").trimEnd();
+  const entries = starts.map((start, n) =>
+    lines.slice(start, starts[n + 1] ?? lines.length).join("\n").trimEnd()
+  );
+
+  return { header, entries };
+}
+
+function entryMonth(entry) {
+  const match = entry.match(/^## (\d{4}-\d{2})/);
+  return match ? match[1] : "undated";
+}
+
+async function archiveByMonth(directory, entries) {
+  await mkdir(directory, { recursive: true });
+
+  const byMonth = new Map();
+  for (const entry of entries) {
+    const month = entryMonth(entry);
+    byMonth.set(month, [...(byMonth.get(month) ?? []), entry]);
+  }
+  for (const [month, monthEntries] of byMonth) {
+    await appendFile(
+      path.join(directory, `${month}.md`),
+      `${monthEntries.join("\n\n")}\n\n`,
+      "utf8"
+    );
+  }
+}
+
+async function writeHotFile(filePath, header, pointer, entries) {
+  const headerWithPointer = header.includes(pointer) ? header : `${header}\n\n${pointer}`;
+  await writeFile(filePath, `${[headerWithPointer, ...entries].join("\n\n")}\n`, "utf8");
+}
+
+const progressPath = path.join(ROOT, "progress.md");
+const { header, entries } = splitEntries(await readFile(progressPath, "utf8"));
+const archivedEntries = entries.slice(0, Math.max(0, entries.length - KEEP_ENTRIES));
+const keptEntries = entries.slice(-KEEP_ENTRIES);
+
+if (archivedEntries.length > 0) {
+  await archiveByMonth(path.join(ROOT, "memory", "progress"), archivedEntries);
+  await writeHotFile(
+    progressPath,
+    header,
+    "Older entries: see `memory/progress/`.",
+    keptEntries
+  );
+}
+
+let archivedLessons = 0;
+const lessonsPath = path.join(ROOT, "lessons.md");
+try {
+  const { header: lessonsHeader, entries: lessonsEntries } = splitEntries(await readFile(lessonsPath, "utf8"));
+  const promoted = lessonsEntries.filter((entry) => /\n- Status: promoted:/.test(entry));
+  const pending = lessonsEntries.filter((entry) => !/\n- Status: promoted:/.test(entry));
+
+  if (promoted.length > 0) {
+    await archiveByMonth(path.join(ROOT, "memory", "lessons"), promoted);
+    await writeHotFile(
+      lessonsPath,
+      lessonsHeader,
+      "Promoted lessons: see `memory/lessons/`.",
+      pending
+    );
+    archivedLessons = promoted.length;
+  }
+} catch (error) {
+  if (error.code !== "ENOENT") {
+    throw error;
+  }
+}
+
+const featuresPath = path.join(ROOT, "feature_list.json");
+const features = JSON.parse(await readFile(featuresPath, "utf8"));
+const verified = features.filter((feature) => feature.status === "verified");
+const active = features.filter((feature) => feature.status !== "verified");
+
+if (verified.length > 0) {
+  const archivePath = path.join(ROOT, "memory", "features-archive.json");
+  await mkdir(path.join(ROOT, "memory"), { recursive: true });
+
+  let archive = [];
+  try {
+    archive = JSON.parse(await readFile(archivePath, "utf8"));
+  } catch {
+    // first rotation: archive file does not exist yet
+  }
+
+  await writeFile(archivePath, `${JSON.stringify([...archive, ...verified], null, 2)}\n`, "utf8");
+  await writeFile(featuresPath, `${JSON.stringify(active, null, 2)}\n`, "utf8");
+}
+
+console.log(
+  `Archived ${archivedEntries.length} progress entries, ${verified.length} verified features, ` +
+  `and ${archivedLessons} promoted lessons to memory/.`
+);