vietreport-admin/solution-erp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7875b3986162a1da2b2ded17e028921cfd1b61ee
solution-erp/.claude/workflows/runs/README.md
pqhuy1987 8c47bd0f0c
All checks were successful
Deploy SOLUTION_ERP / build-deploy (push) Successful in 5m36s
Details
[CLAUDE] Docs: adopt Harness-10 — tracked run-trace folder convention + checklist 9-10 (3-workflow invest/imple/review) 
Migrate .claude/workflows/wave-*/ (gitignored) -> runs/<run-id>/ git-TRACKED (run.md+sub-md/+harvest/) + _ledger.md 2-beat + 3-layer anti-miss + containment model shift (B6 'any tracked-change=violation' -> 'tracked-change outside run-folder+code-disjoint=violation'). hmw.js wave->run-trace (accept args.run + alias). Review (R2+R3) caught C5 L1 over-claim -> fixed (em-main convention, engine no-fs). 3 run-id: wf_9c2cd2cd-2e7 / wf_e4e46725-231 / wf_636bc95b-939. 0 production code, state unchanged (Mig 53/88 tables/306 test/68 gotcha).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-18 09:15:51 +07:00

7.5 KiB
Raw Blame History

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