solution-erp/.claude/workflows/runs/README.md

runs/ — Run-trace convention (Harness-10 · cấu trúc PHẲNG)

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 + bản-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) + DELTA h10-flat-detector-refine (06-18). Convention cha: ../README.md.

🆕 REFINE 06-18 — cấu trúc PHẲNG. Trước đây mỗi run-folder có 2 thư mục con (sub-md/ + harvest/). NAY mọi vết tích nằm phẳng cùng MỘT cấp trong runs/<run-id>/; phân biệt bản-thô (raw, per-sub) vs bản-đã-soát (verified, gom) bằng TÊN file, KHÔNG bằng thư mục con. Lý do: engine (hmw.js JS-sandbox no-fs) chỉ tạo artifact ở một cấp một cách tự nhiên — bỏ thư-mục-con sâu thì xoá luôn một điểm-hay-quên ngay tại gốc (không còn thư-mục-con-để-quên-dựng).

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

---

C1 — Cấu trúc PHẲNG (mỗi runs/<run-id>/ — file cùng MỘT cấp)

runs/<run-id>/
├── run.md                       ← (1) PLAN — em main @P1: meta + mục-tiêu + agents-table + guards + status OPEN→CLOSE
├── sub-<role>-<i>.md            ← (2) PER-SUB raw — 1 file/sub/turn, prefix `sub-` (vd sub-investigator-codebase-0.md)
├── sub-<role>-<i>.md                (fan-out cùng-role → đánh số -0 / -1 …)
└── <stage>-synthesis.md         ← (3) GOM verified — em main: bản-gom 1 turn, suffix `-synthesis.md` (vd invest-synthesis.md)

Phân-biệt raw vs verified bằng TÊN, KHÔNG bằng subfolder:

Loại	Quy-ước TÊN	Ai ghi	Nội-dung
PLAN	run.md (cố định)	em main @P1	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, status OPEN→CLOSE.
PER-SUB (raw)	prefix sub- → sub-<role>-<i>.md	write-sub tự ghi @P2 · read-only sub → em main scribe @P3	full working detail 1 sub. 1 sub-MD / role / turn (cùng-role → -0/-1). Read-only sub (CHỈ Bash) KHÔNG Bash-write MD (mojibake) → trả findings+subMdPath, em main single-writer.
GOM (verified)	suffix -synthesis.md → <stage>-synthesis.md	em main per-turn (C4)	gom sub-*+findings → 5-trục integrity → build-spec/synthesis.

🟢 Quy-tắc nhận-diện: file bắt đầu bằng sub- = bản-thô (per-sub); file kết bằng -synthesis.md = bản-đã-soát (gom). run.md = plan. Không cần mở file/không cần subfolder để biết loại — đọc TÊN là đủ. (Khớp ../hmw.js inject path: engine ghi-direct runs/<run-id>/sub-<role>-<i>.md, KHÔNG sub-md/….)

Live dogfood: 2026-06-18-harness-audit-invest/ = run.md + audit-synthesis.md CHỈ (KHÔNG subfolder, KHÔNG raw sub-audit-*.md) — vì 1 auditor fail-no-StructuredOutput + 2 truncated → em main self-gate ground-truth từ đĩa, không có raw-sub để scribe (xem audit-synthesis.md:4). Ví-dụ tên sub-<role>-<i>.md là minh-hoạ QUY-TẮC-ĐẶT-TÊN, KHÔNG phải artifact bắt-buộc mỗi run. Run 2026-06-18-harness-fix-implement/ mới có đủ raw (sub-impl-sleepcmd.md + sub-impl-runsreadme.md + implement-synthesis.md) = full flat set điển-hình.

---

C2 — Scaffold run.md ở OPEN (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:

1. Tạo run-folder + PLAN: runs/<run-id>/run.md (điền plan đầy-đủ). 🆕 KHÔNG cần mkdir sub-md/ / harvest/ / .gitkeep — file sub-* và *-synthesis.md sẽ sinh ra phẳng cùng cấp trong cùng folder đó (engine + em main ghi 1 cấp).
2. Ghi OPEN-beat vào runs/_ledger.md (1 dòng, closed=⏳).
3. (nối stage) trỏ input spec: trong run.md sang <stage>-synthesis.md của run trước (vd implement đọc invest-synthesis.md).

🔴 C2 là fragile-point. Quên 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. 🆕 Cấu trúc phẳng bỏ 1 trong 2 điểm-hay-quên (không còn subfolder-to-forget); dư-lượng còn lại = vẫn phải tự ghi <stage>-synthesis.md mỗi run (close-gate C5/L3 bắt nếu thiếu).

---

C3 — Git-tracked: VERIFY 2 nấc tách-bạch (chỗ hay nhầm)

Run-folder PHẢI git TRACKED (re-include qua .gitignore:83 !.claude/**, last-match-wins). Verify ĐỦ 2 nấc — đừng dừng ở nấc 1:

# Nấc (i) — GỠ-KHỎI-IGNORE (tracked-eligible): exit != 0 = KHÔNG bị ignore
git check-ignore .claude/workflows/runs ; echo "exit=$?"     # SE: exit=1 ✓ (không ignore)

# Nấc (ii) — THẬT-SỰ-COMMIT: liệt-kê ra file = đã `git add`/commit
git ls-files .claude/workflows/runs | wc -l                   # SE: 22 ✓ (non-empty = đã commit)

• Nấc (i) check-ignore exit != 0 = thư-mục KHÔNG nằm trong ignore (tracked-eligible). ⚠️ Mới là đủ-điều-kiện-track, CHƯA chắc đã commit.
• Nấc (ii) ls-files non-empty = thật-sự có file trong index (đã git add/commit). 🔴 eligible ≠ committed: một folder check-ignore exit!=0 NHƯNG ls-files rỗng = chưa hề commit (bằng-chứng sống tại AI_INFRA chính trường-hợp này). PHẢI chạy CẢ 2 lệnh.
• 🔴 ĐÚNG PATH mới đáng tin. Path đúng = .claude/workflows/runs (đầy-đủ từ repo-root). Bare runs/ (tên trần) là path SAI — ở repo khác, git check-ignore runs từ repo-root có thể trả exit 0 (match nhầm rule khác / không match negation .claude/**) → đọc sai thành "bị ignore". (Quan-sát SE: cả runs lẫn .claude/workflows/runs đều trả exit=1 vì .gitignore SE không có rule runs trần — nhưng ĐỪNG dựa may-rủi đó: luôn dùng path đầy-đủ .claude/workflows/runs.)
• Bẫy exit-code khi dùng -v: git check-ignore -v <path> trả exit 0 cho CẢ ignore lẫn negation (!.claude/**) → đừng đọc exit của -v để kết-luận; dùng dạng không--v ở trên (exit!=0 = không ignore) hoặc && echo IGNORED || echo NOT.

---

C4 — Per-turn primary (gom NGAY, không đợi session-end)

Gom là việc của turn, không defer. Sau MỖI fan-out turn → em main đọc sub-*+findings → ghi <stage>-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). Đây là đường CHÍNH (primary); gom toàn-bộ @session-end (L3) chỉ là lưới an-toàn (safety-net), KHÔNG phải đường chính.

---

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 ledger-check	em-main @P1, lúc mở run mới (TRƯỚC scaffold)	đọc _ledger.md: nếu run TRƯỚC còn closed=⏳ (OPEN-beat chưa CLOSE / thiếu <stage>-synthesis.md) → gom + 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 orphan-scan	đầu session (session-start.md §2.1.1 H2)	scan runs/*/ tìm orphan = OPEN-beat (ledger closed=⏳) mà KHÔNG có <stage>-synthesis.md → báo + giải-quyết (C6).
L3 session-end close-gate	cuối session (session-end.md §L.b(f) H2)	VERIFY per-turn gom đã xong cho mọi runs/<id>/ (idempotent — KHÔNG re-APPEND, chống DUPLICATE-HARVEST) + 5-trục GATE backstop trước khi commit. 🆕 close-gate chấp nhận CẢ 2 dạng (old-subfolder + new-flat) trong giai-đoạn chuyển — xem C8.

3 layer độc-lập, fire ở 3 thời-điểm khác nhau (run-open @P1 / session-start / session-end) — KHÔNG layer nào do engine enforce (hmw.js no-fs), cả 3 là convention em-main/H2. → 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 (session sau) / L3 (close-gate).

---

C6 — Ledger 2-nhịp + orphan resolution (_ledger.md)

Sổ tất-cả run, 1 bảng. Mỗi run 2 lần ghi (2-nhịp):

• OPEN-beat (@P1, lúc scaffold): thêm dòng | <run-id> | <workflow> | <opened> | ⏳ | <agents> | ⏳ | <stage>-synthesis.md |.
• 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).

Orphan = dòng ledger closed=⏳ nhưng run thực-tế đã xong/bỏ (session bị kill, agent die-0-byte, quên CLOSE-beat). Giải-quyết-CỨNG (không để treo):

1. Điều-tra đĩa THẬT: run.md status + có file sub-*? + có <stage>-synthesis.md? + 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 (JS-sandbox no-filesystem) KHÔNG tạo được folder/file. Run-trace dựa 100% vào em-main: scaffold run.md @P1 (C2) + tự ghi <stage>-synthesis.md mỗi run (C4). Không có cơ-chế nào ép tạo file. NOT fully-autonomous — đây là hard-gate-trên-INPUT (em main tự dựng khung + tự bơm tham-số đầu/cuối mỗi run), KHÔNG phải engine tự-động.
• Cấu trúc phẳng giảm fragile từ 2 → 1, KHÔNG triệt-tiêu. Bỏ subfolder xoá được điểm-hay-quên "dựng sẵn sub-md/+harvest/" (engine giờ ghi 1 cấp, no subfolder-to-forget). NHƯNG còn dư-lượng: em-main VẪN phải nhớ ghi <stage>-synthesis.md mỗi run (close-gate L3 bắt nếu thiếu). Điểm-yếu giảm 1-trong-2, chứ không biến mất → C2 vẫn bắt-buộc.
• 3-layer = LƯỚI, KHÔNG khoá-cứng-cùng-lúc-fire. L1/L2/L3 bắt lỗi sau khi việc đã xảy ra (post-hoc) hoặc nhắc dựa-trên-input em-main-bơm — giảm xác-suất sót, KHÔNG chặn tại-đúng-thời-điểm-fire. Phòng-thủ-nhiều-lớp, KHÔNG bảo-đảm tuyệt-đối.
• 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 (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".

---

C8 — MIGRATION (run cũ giữ subfolder · close-gate chấp-nhận CẢ 2 dạng)

🔴 KHÔNG viết lại lịch-sử. 5 run-folder S71 đã chốt giữ NGUYÊN cấu trúc cũ sub-md/ + harvest/ (đã commit, KHÔNG đụng):

2026-06-18-h10-invest/      (run.md + sub-md/ + harvest/invest-synthesis.md)     ← cũ, GIỮ
2026-06-18-h10-implement/   (run.md + sub-md/ + harvest/implement-synthesis.md)  ← cũ, GIỮ
2026-06-18-h10-review/      (run.md + sub-md/ + harvest/review-synthesis.md)      ← cũ, GIỮ
2026-06-18-h910-finalize/   (run.md + sub-md/ + harvest/finalize-synthesis.md)   ← cũ, GIỮ
2026-06-18-h910-curate/     (run.md + sub-md/ + harvest/curate-synthesis.md)     ← cũ, GIỮ
2026-06-18-harness-audit-invest/  (run.md + audit-synthesis.md)                  ← 🆕 FLAT

• Run MỚI từ refine 06-18 → dùng FLAT (sub-<role>-<i>.md + <stage>-synthesis.md cùng cấp). Run CŨ → để yên (đừng gom-lên-cấp/đừng xoá subfolder — re-writing history vô-ích + làm bẩn git-log).
• 🟢 Close-gate (L3) ACCEPT BOTH suốt giai-đoạn chuyển: verify gom ở harvest/<stage>-synthesis.md (dạng cũ) HOẶC <stage>-synthesis.md phẳng (dạng mới). Không fail run cũ chỉ vì thiếu file-phẳng.
• 2 nấc track (C3) áp cho CẢ 2 dạng: check-ignore exit!=0 + ls-files non-empty.

---

Containment model (PHẢI khớp _ledger.md + ../hmw.js — đồng-bộ 3 chỗ: đây · _ledger.md · ../hmw.js)

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).

---

Anti-bypass detector — SE TAILORED-OUT (quyết-định có chủ-đích, anh chốt)

Refine 06-18 (b) đề-xuất làm-chặt một bộ-dò chống-lách-engine (soi nhật-ký/mã xem có run nào né engine chuẩn không) theo 3 chức-năng. SE quyết-định KHÔNG hiện-thực bộ-dò này — đã CÂN-NHẮC và thấy N/A cho threat-model của SE. Giữ trung-thực, KHÔNG overclaim "đã có anti-bypass detector".

Lý-do tailored-out:

• SE chạy workflow qua Anthropic Workflow tool (hmw.js invoke), KHÔNG có bề-mặt-lách kiểu CLI-launcher. AI_INFRA threat-model giả-định một node-CLI launcher (đường-vòng chạy lén engine) cần bộ-dò canh. SE không có launcher như vậy → không có "đường-vòng" để dò.
• Containment SE đã đủ bằng cơ-chế khác (G-015 defense-in-depth): git diff commit-gate (mọi write tracked HIỆN trong diff) + run-folder git-tracked (audit trực-tiếp) + _ledger.md orphan-scan (L2/L3) — backstop THẬT (không phải prompt). Bộ-dò pattern-match thêm = trùng-lặp, không bịt lỗ mới.

3 chức-năng refine — CÂN-NHẮC rồi N/A cho SE:

Chức-năng refine (b)	Áp SE?	Vì sao
(1) Whitelist launcher hợp-lệ	N/A	SE không có launcher-wrapper quanh engine → không có gì để whitelist.
(2) Khớp đa-dạng biến-thể path tới engine	N/A	SE invoke engine qua Workflow tool (1 đường duy-nhất), không có path-variant để khớp.
(3) Neo KHOÁ-khởi-chạy-thật (đừng match tên-engine lẫn trong script) + acceptance theo QUAN-HỆ	N/A	Không có log-scan detector → không có chỗ neo launch-key. Acceptance-by-relation (hợp-lệ ≠ vi-phạm, hợp-lệ tăng dần OK) là nguyên-tắc tốt nhưng chỉ áp được khi CÓ detector.

🔴 No-overclaim: SE KHÔNG claim đã adopt anti-bypass detector. SE claim: đã đọc + cân-nhắc 3 chức-năng, chọn tailored-out vì threat-model SE không có CLI-launcher-bypass-surface; containment dựa git-diff + run-folder-tracked + ledger-orphan-scan (G-015). Nếu sau này SE thêm launcher-wrapper → re-visit quyết-định này.