# `runs/` — Run-trace convention (Harness-10)

> **Mục đích:** mỗi workflow fan-out (RUN-TRACE mode) ghi lại 1 dấu-vết hoàn-chỉnh trong `runs/<run-id>/` git **TRACKED** — plan + per-sub detail + harvest gom — cộng sổ `_ledger.md` 2-nhịp. TRACKED nghĩa là mọi write trong run-folder hiện trong `git diff` → **audit trực-tiếp**, không cần tin lời agent return. Adopt AI_INFRA Harness-10 (anh 06-18). Convention cha: `../README.md`.

**run-id** = `YYYY-MM-DD-h<NN>-<slug>` (vd `2026-06-18-h10-invest`). Nhiều run cùng ngày → slug phân-biệt stage (`-invest` / `-implement` / `-review`).

---

## C1 — Cấu trúc 3 phần (mỗi `runs/<run-id>/`)
```
runs/<run-id>/
├── run.md                          ← (1) PLAN — em main @P1: meta + mục-tiêu + agents-table + guards + status OPEN→CLOSE
├── sub-md/                         ← (2) PER-SUB — 1 file/sub/turn: <role>-<i>.md (vd investigator-codebase-0.md)
│   └── .gitkeep                       (giữ folder rỗng trong git khi chưa có write-sub)
└── harvest/                        ← (3) HARVEST — em main: <topic>-synthesis.md gom kết-quả turn (C4 per-turn)
    └── .gitkeep
```
- **(1) `run.md`** — nguồn-sự-thật của run: workflow run-id (evidence B3 `wf_…`), adap/mandate, checkpoint, opened, input-spec (nếu nối stage trước), agents-table (`# · role · task`), guards áp cho sub, output-path. Mẫu: `2026-06-18-h10-invest/run.md`.
- **(2) `sub-md/<role>-<i>.md`** — full working detail 1 sub. Write-sub (Write/Edit) tự ghi @P2; read-only sub (CHỈ Bash) → trả `findings`+`subMdPath`, **em main scribe @P3** (single-writer, tránh mojibake). **1 sub-MD / role / turn** (fan-out cùng-role → đánh số `-0`/`-1`).
- **(3) `harvest/<topic>-synthesis.md`** — em main gom `sub-md/`+findings → 5-trục integrity → build-spec/synthesis. Mẫu: `2026-06-18-h10-invest/harvest/invest-synthesis.md`.

---

## C2 — Scaffold ở CẢ 3 đầu-run (em main @P1, TRƯỚC khi invoke Workflow)
`hmw.js` chạy JS-sandbox **no-filesystem** → KHÔNG tự tạo folder/file. Em main PHẢI Write @P1, đủ **3 đầu**:
1. **Tạo run-folder:** `runs/<run-id>/run.md` (điền plan) + `sub-md/.gitkeep` + `harvest/.gitkeep`.
2. **Ghi OPEN-beat** vào `runs/_ledger.md` (1 dòng, `closed=⏳`).
3. **(nối stage)** trỏ `input spec:` trong `run.md` sang `harvest/` của run trước (vd implement đọc invest-synthesis).

> 🔴 **C2 là fragile-point.** Quên bước scaffold = run chạy nhưng KHÔNG có dấu-vết = **lỗ-hổng âm-thầm** (không lỗi, không cảnh-báo — chỉ thiếu file). 3-layer (C5) là lưới giảm-thiểu, KHÔNG khoá-cứng. Xem C7.

---

## C3 — Ledger 2-nhịp (`_ledger.md`)
Sổ tất-cả run, 1 bảng. Mỗi run **2 lần ghi**:
- **OPEN-beat** (@P1, lúc scaffold): thêm dòng `| <run-id> | <workflow> | <opened> | ⏳ | <agents> | ⏳ | harvest/ |`.
- **CLOSE-beat** (lúc đóng run): điền `closed` timestamp + `verdict` (PASS/FAIL + 1 dòng + `wf_…`) + `harvest` (path file synthesis ✓).

`closed=⏳` = đang chạy (OPEN chưa CLOSE).

---

## C4 — Per-turn primary (harvest NGAY, không đợi session-end)
Harvest là **việc của turn**, không defer. Sau MỖI fan-out turn → em main đọc `sub-md/`+findings → ghi `harvest/<topic>-synthesis.md` **liền trong turn đó** (chính file synthesis này là bằng-chứng). Lợi: detail tươi, không mất qua nén-context; session-end chỉ VERIFY (không tái-tạo).

---

## C5 — 3-layer anti-miss (lưới chống bỏ-sót, KHÔNG khoá-cứng-cùng-lúc-fire)
| Layer | Khi | Làm gì |
|---|---|---|
| **L1 in-run reminder** | lúc mở run mới (em-main @P1, TRƯỚC scaffold) | em-main đọc `_ledger.md`: nếu run TRƯỚC còn `closed=⏳` (OPEN-beat chưa CLOSE / `harvest/` rỗng) → harvest + CLOSE nó TRƯỚC khi mở run mới. *(Engine no-fs → KHÔNG đọc được ledger → L1 là convention EM-MAIN, KHÔNG phải `hmw.js` prompt. hmw.js chỉ emit C4 per-turn return-instruction cho sub tại writeGuard.)* |
| **L2 session-start rescan** | đầu session (`session-start.md` §2.1.1 H2) | scan `runs/*/` tìm **OPEN-beat (ledger `closed=⏳`) mà `harvest/` rỗng = orphan** → báo + giải-quyết. |
| **L3 session-end close-gate** | cuối session (`session-end.md` §L.b(f) H2) | VERIFY per-turn harvest đã xong cho mọi `runs/<id>/` (**idempotent — KHÔNG re-APPEND**, chống DUPLICATE-HARVEST) + 5-trục GATE backstop trước khi commit. |

> 3 layer **độc-lập, fire ở 3 thời-điểm khác nhau** — không layer nào enforce lúc-ghi. Bỏ-sót ở P1 (C2) chỉ bị bắt MUỘN (L2 session sau / L3 close-gate), không chặn tại-chỗ.

---

## C6 — Orphan resolution (OPEN không CLOSE)
**Orphan** = dòng ledger `closed=⏳` nhưng run thực-tế đã xong/bỏ (vd session bị kill, agent die-0-byte, quên CLOSE-beat).
- **Phát-hiện:** L2 session-start rescan (`closed=⏳` + `harvest/` trạng-thái) hoặc L3 close-gate.
- **Giải-quyết-CỨNG** (không để treo):
  1. **Điều-tra** đĩa THẬT: `run.md` status + `sub-md/` có detail? + `harvest/` có synthesis? + git-log workflow `wf_…`.
  2. **Đóng tay** nếu run thật-sự xong: điền CLOSE-beat (timestamp + verdict + harvest path).
  3. **Đánh-dấu aborted** nếu run bỏ-dở: verdict = `⚠️ ABORTED — <lý-do>`, ghi rõ phần nào hoàn-thành (recover qua git/disk/prod truth, KHÔNG tin agent return-message).

---

## C7 — 🔴 CAVEAT trung-thực (no-overclaim)
- **Engine no-fs → scaffold KHÔNG tự-động.** `hmw.js` (`:4` no hot-reload, JS-sandbox no-filesystem) KHÔNG tạo được folder. Run-trace dựa **100% vào em-main Write @P1** (C2). Không có cơ-chế nào ép tạo folder.
- **C2 = fragile-point.** Quên scaffold = lỗ-hổng âm-thầm (run chạy OK, chỉ mất dấu-vết). Không lỗi runtime để bắt.
- **3-layer = LƯỚI, KHÔNG khoá-cứng-cùng-lúc-fire.** L1/L2/L3 fire ở 3 thời-điểm khác nhau (run-open @P1 / session-start / session-end), **cả 3 đều là convention em-main/H2 — KHÔNG layer nào do engine enforce** (hmw.js no-fs). → giảm xác-suất sót, KHÔNG triệt-tiêu. Sót P1 (C2) cùng blind-spot với L1 (đều @P1) → chỉ bắt MUỘN ở L2/L3.
- **G-015 no-overclaim — TRACKED ≠ read-only-ENFORCED.** Run-folder git-tracked KHÔNG biến sub thành read-only: sub **vẫn giữ Bash** (write-channel mở — ghi-ngoài-repo git-diff mù / curl Qdrant). Containment THẬT (xem model dưới) = em-main single-writer + git-diff(in-repo) + chunk-count(RAG), defense-in-depth — KHÔNG sandbox cứng, KHÔNG claim "ENFORCED".

---

## Containment model (PHẢI khớp `_ledger.md:4` — đồng-bộ 3 chỗ: đây · `_ledger.md` · `../hmw.js:112`)
> Run-folder `runs/<run-id>/` được git **TRACKED** → mọi write **HIỆN** trong git-diff = **audit trực-tiếp**. Containment: tracked-change **NGOÀI** `runs/<run-id>/` **VÀ NGOÀI** code-disjoint đã giao = **vi-phạm** (thay model Harness-2 B6 "mọi tracked-change = vi-phạm"). G-015 no-overclaim: TRACKED ≠ read-only-enforced — sub vẫn giữ Bash (write-channel mở), containment THẬT = em-main single-writer + git-diff(in-repo) + chunk-count(RAG).

**Verify pattern:** `git check-ignore -v <path>` — bẫy exit-code (exit 0 cho CẢ negation `!.claude/**` lẫn ignore) → dùng `&& IGNORED || NOT` để đọc đúng. Run-folder match `:83 !.claude/**` = re-included = TRACKED (HIỆN trong diff).