solution-erp/.claude/workflows/runs/2026-07-12-h22-wal-adopt/spec-h22-wal-adopt-12-07-2026.md

# SPEC — h22-wal-adopt — 12-07-2026 (S111)

> **Provenance (H21 note-c):** engine-propose = investigator-codebase **Fable-real single-deep-pass** (lệnh-A anh gõ `/fable-real invest và review — đề tài harness AI_INFRA apply xuống`; return SẠCH 0-garble, VERDICT `READY_WITH_NUANCES` 14 nuance N1-N14) → **lead verified + CHỈNH 3 điểm**: (1) **D2 hook = PowerShell `.ps1` variant** thay bash-nguồn — evidence xung-đột 2-context: lead đo PS-context `Get-Command bash` → `C:\WINDOWS\system32\bash.exe` WSL-HỎNG (execvpe fail) vs invest đo cmd-context `where bash` → Git-Bash đứng trước; exec-env hook thật KHÔNG xác định được trong phiên → chọn path-independent `powershell.exe` (system32, tuyệt đối); port NGUYÊN semantics sàn (per-path add + CAND commit + exit-0 mọi nhánh + 0 content/push/block); script-RUN verify tay được ngay phiên này — hook-FIRE vẫn phiên mới (N1 STAGED giữ) · (2) row #9 acceptance = `node --check` PASS (precedent S110 X7, bỏ wording mơ hồ) · (3) `.gitattributes` `*.sh text eol=lf` VẪN append (phòng-hờ .sh tương lai + fleet-parity, vô hại — repo hiện 0 file .sh) → **lead tự ghi file này** (single-writer). Worker KHÔNG tự đọc file — lead bơm nguyên văn qua args (hmw.js pattern).

## Mục 1 — Tính-năng / đề-bài

Adopt **Harness-22 WAL session-continuity** (broadcast `2026-07-11-Governance-harness-22-wal-session-continuity`, body-sha `3de0758a6377` verified): sổ `.claude/WAL.md` ≤40 dòng ghi-đè-không-append (chain-bằng-chứng `[x]/[!]/[ ]` + next 1-mệnh-lệnh + verify-trước-next, ground-truth thắng, cấm secret) · Stop-hook `.claude/hooks/wal-flush.ps1` persist-only per-path+CAND+exit-0 (**STAGED-until-verified** — hook nạp lúc khởi-động phiên, phiên này KHÔNG THỂ verify fire) + `.gitattributes` `*.sh text eol=lf` append · cặp `/pause` `/tiep` (MỘT đường recovery duy nhất) · delta session-start (**BƯỚC 0.7 MỚI** WAL-check — ngoại-lệ CHỜ duy nhất) + session-end (**§5.0** squash `wal:` trailing chưa-push + **§6.4** reset-WAL bước cuối) · WAL-cho-workflow (mandate run-trace ≥3-task/>5', taskList-snapshot vào run.md, dòng `wf:` 5-trường, harvest-liền C4 + per-agent-file + honest per-turn≠per-task N9, /tiep = relaunch-cắt-gọt + memory-pack re-derive tươi, resume-run-id = bonus SAME-SESSION-ONLY) · codify engine **PHẦN N** + CAVEAT:402 honest-update + rules §5.2 exception `wal:` + CLAUDE.md 2-dòng con-trỏ + honest (a)-(e) áp SE (e = Dropbox 2-chiều: risk index.lock + bonus .git-sync durability).

**Xong nghĩa là (DoD grep-được):** `Test-Path .claude/WAL.md`=True và ≤40 dòng · `.claude/hooks/wal-flush.ps1` chạy tay exit-0 + tạo commit `wal:` thật (script-RUN verified; hook-FIRE = phiên mới) · grep `"Stop"` `.claude/settings.json` ≥1 · grep `*.sh text eol=lf` `.gitattributes` =1 · grep `wal:` `docs/rules.md` ≥1 · grep `BƯỚC 0.7` session-start.md =1 · grep `reset --soft` session-end.md ≥1 · engine grep `PHẦN N` ≥1 + `STAGED-until-verified` ≥1 + honest (a)-(e) đủ 5 · CLAUDE.md grep `/tiep` ≥1 · workflows/README.md vùng :31 có `BẮT BUỘC` · adap-report + email AI_INFRA + mark-proposal trình anh (CHƯA stamp) · HANDOFF NEXT-anh có pilot-checklist + restart-CLI note.

## Mục 2 — Cách implement

### Quyết định thiết kế
- **D1 — WAL.md:** template rỗng nguồn §2 NGUYÊN VĂN; tracked (verify idiom N12: `git check-ignore` exit-1 = NOT-IGNORED cho re-included path `!.claude/**` .gitignore:82-83 — đừng đọc exit-code trần); ghi-đè toàn-file mỗi lần; lead single-writer nội-dung sau MỖI subtask đổi trạng-thái; dogfood ghi-chain ngay trong phiên S111 này.
- **D2 — Hook (LEAD-CHỈNH PS1):** `.claude/hooks/wal-flush.ps1` port NGUYÊN logic nguồn §3: 3 path cố định `.claude/WAL.md` + `.claude/agent-memory/` + `.claude/workflows/runs/` (N3 — GIỮ NGUYÊN, AS-6 không tăng: 2 json churn `.mfe-state`/`.archive-strikes` đã gitignored :124-125, `memory-budget.json` tracked đổi-hiếm-owner-directed; hook chỉ commit LOCAL, CI trigger lúc PUSH, squash → push-set ≡ hôm nay); **per-path `git add` từng cái** (X3 — add đa-pathspec = all-or-nothing khi 1 path vắng, bài học đắt nguồn) + CAND-list chỉ path thực-có-staged + commit `-m "wal: flush <yyyyMMddTHHmm>"` KHÔNG Co-Authored-By + **exit 0 MỌI nhánh** (try/catch bọc toàn thân; Stop-hook exit≠0 có hành vi riêng — CẤM); KHÔNG content-gen, KHÔNG push, KHÔNG block-stop, KHÔNG path ngoài list. `settings.json` CREATE MỚI (N1 — file chưa tồn tại, merge-concern moot) nested-schema: `{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"powershell.exe -ExecutionPolicy Bypass -File .claude/hooks/wal-flush.ps1"}]}]}}`. **Status = STAGED-until-verified** (X5): codify + enable cùng commit nhưng CẤM claim "đang chạy" trước khi thấy commit `wal:` do HOOK sinh trong `git log` phiên MỚI (script-RUN tay ≠ hook-FIRE); honest-note (c) nguồn: nếu phiên mới không fire → thử biến-thể phẳng rồi verify lại.
- **D3 — /pause /tiep:** GIỮ tên nguồn (N11 — 16 command hiện có, 0 trùng); `.claude/commands/pause.md` = logic nguồn §4 /pause 5-bước (ngừng-spawn → flush-dirty → WAL-đúng-schema → commit ĐÍCH-DANH `wal: pause` KHÔNG `git add -A` → báo-cáo + DỪNG HẲN; bất-biến: commit TRƯỚC tuyên-bố an-toàn); `.claude/commands/tiep.md` = nguồn §4 /tiep 4-bước + nhánh `wf:` §6 (đọc WAL → không-tồn-tại/toàn-`[x]` = báo "không có mạch dở" DỪNG SẠCH → chạy TOÀN BỘ verify → lệch = TIN GROUND-TRUTH sửa WAL trước → thực-thi next; mục `wf:` → relaunch-CẮT-GỌT: đọc run-folder + taskList-snapshot, grep run-id trong log-phiên = bằng-chứng đích-danh task-đã-xong, harvest-hồi-tố partial-honest [lead verify rồi append], relaunch CHỈ task còn lại + memory-pack RE-DERIVE TƯƠI); /tiep verify đọc CẢ `git status` + disk run-folder KHÔNG chỉ git-log (N9); CẤM nạp transcript cũ; field `session:` khác phiên = BÌNH-THƯỜNG, chỉ cảnh-báo nếu `updated` mới hơn lúc phiên hiện-tại bắt đầu.
- **D4 — session-start:** **BƯỚC 0.7 MỚI** chèn sau BƯỚC 0.6 (:37-45) TRƯỚC Phase 1 READ (:47) — chặn trước read-set ~368K = token-save lớn nhất (N6); nội dung: đọc `.claude/WAL.md` → có `[!]` hoặc `[ ]` → báo "có mạch dở, `/tiep` để nối" + **CHỜ anh chọn** (ngoại-lệ CHỜ DUY NHẤT của quy-trình no-wait; chỉ là CON-TRỎ — quy-trình recovery viết ở MỘT chỗ = tiep.md); chain rỗng/toàn-`[x]` → tiếp bình-thường. GIỮ NGUYÊN số 0.5/0.5b/0.6 (X10, precedent D4 S110 chống renumber-churn).
- **D5 — session-end:** **§5.0 MỚI** ngay trước §5.1 (:111): đếm K = subject liên-tục `^wal:` từ HEAD xuống trong `git log --format=%s origin/main..HEAD` (span CHƯA-push — không bao giờ rewrite đã-push X4) → K>0 → `git reset --soft HEAD~K` gộp vào commit-chốt; K=0 → skip; biên N7: (i) push chết phiên trước → HEAD=chốt-cũ-chưa-push KHÔNG bị fold (đếm dừng ở subject ≠wal:), được push lần này; (ii) wal: sandwiched dưới chốt → GIỮ (noise chấp nhận, per nguồn §5); +1 dòng N14: "squash xong = điểm review-diff wal-paths (AS-10 backstop dời về đây, KHÔNG mất — push vẫn gated em-main)". **§6.4 MỚI** sau §6.3 (:129) TRƯỚC footer :139: reset WAL về template rỗng = bước CUỐI (hook sẽ commit lần reset thành wal-commit trailing sau turn cuối — vô-hại, phiên sau squash).
- **D6 — WAL-cho-workflow:** `workflows/README.md:31` + bảng :24 FLIP policy: mode-A vẫn cho fan-out NHỎ, nhưng **run ≥3 task HOẶC ước >5 phút = BẮT BUỘC RUN-TRACE mode (args.run — per-agent-file trong run-folder)** (sàn H22 owner nguồn đã chốt); run.md template +section `## taskList snapshot` (role · label · prompt-gist) ghi TRƯỚC launch (N10); dòng `wf:<mục-đích> run=<folder> runId=<id|pending> args=<snapshot-ref> done=<k>/<N> harvested=<yes|no|partial>` vào WAL NGAY SAU launch, lead điền runId khi có; harvest-LIỀN mỗi task xong = C4 per-turn (ĐÃ CÓ — hmw.js:99 + session-end:51) + honest-note granularity N9 (per-TURN ≠ per-TASK: `parallel()` trả cả batch cuối turn, Stop-hook cũng fire ở turn-boundary → chết GIỮA turn = returns mất, per-agent-file trên DISK là lớp cứu → /tiep đọc cả disk); memory-pack KHÔNG snapshot (X6 — re-derive tươi lúc /tiep; hiện đã compliant: pack qua args hmw.js:15); resume-by-run-id = bonus SAME-SESSION-ONLY (engine Workflow docs "same-session only" — CẤM claim cross-session, honest-note (d)).
- **D7 — Codify:** engine `docs/governance/harness-11-engine.md` **PHẦN N MỚI** (trước CAVEAT :401): schema WAL + 2 tầng ghi (lead nội-dung ⟂ hook persist) + hook ĐƯỢC làm {git add 3-path, CAND-commit `wal:`} / KHÔNG-ĐƯỢC {content-gen, push, block-stop, path-ngoài-list, exit≠0} + STAGED-until-verified + honest (a)-(e) áp SE [(a) pilot chưa chạy tại SE — kill-test/đổi-acc/hook-fire = phiên mới+anh; (b) SE 0-mark-cấm-hook, N2 mô-tả-vs-luật, thứ-tự codify-trước-enable ĐÃ tôn trọng cùng-commit; (c) nested-schema default, fallback flat nếu phiên mới không fire; (d) resume-run-id same-session-only; (e) Dropbox 2-chiều: risk index.lock thấp-nhưng-có fail-open tự-lành + bonus .git-sync = commit local chưa-push vẫn sống qua tắt-máy/đổi-máy → /pause không cần push vẫn durable]; CAVEAT :402 honest-update: thêm ngoại-lệ đích-danh "Stop-hook wal-flush persist-only (PHẦN N) — 0-content, fail-open, KHÔNG phải gate (E.3-compatible)"; `docs/rules.md` §5.2 (:213-221) append exception: "ngoại-lệ DUY-NHẤT: commit `wal:` (Stop-hook persist + /pause + WAL-reset) — máy sinh, KHÔNG Co-Authored-By, bị squash vào commit-chốt trước push (session-end §5.0)"; root `CLAUDE.md` 2 dòng con-trỏ: "Mạch việc dở nằm ở `.claude/WAL.md`; nối lại DUY-NHẤT bằng `/tiep` — kể cả khi anh gõ 'làm tiếp' bằng text thường. Không tự recovery cách khác."
- **D8 — hmw.js :9/:19 comment-only** (em-main, X7 KHÔNG đổi code): :9 meta note mode-A default → "+ mandate H22: ≥3-task/>5' PHẢI RUN-TRACE (em-main scaffold + set args.run — script no-fs không tự ép, enforcement = convention lead)"; :19 `run: OPTIONAL` → wording mandate-ref.
- **D9 — Mark H22 MỚI** trình anh cuối phiên (P4 report-before-stamp §L.b(h)) — KHÔNG tự stamp (X5-mark); đề xuất §-target: `engine PHẦN N` + `.claude/hooks/` + `session-start BƯỚC 0.7` / `session-end §5.0+§6.4` (≙ AI_INFRA H-22 CANONICAL §I4 + §H1).
- **D10 — Optional KHÔNG-block (owner-OK sau):** deploy.yml paths-ignore +`.claude/agent-memory/**` +`.claude/workflows/runs/**` (precedent `.claude/skills/**` :23) — triệt noise CI khi budget.json đổi; ghi option vào adap-report + HANDOFF, KHÔNG làm trong run này.

### Ràng buộc thật
Worker Opus edit-DIRECT trong PHẠM VI file được giao (3 lane disjoint; residual → em-main git-diff revert AS-10) · WAL.md + .gitattributes + settings.json + engine + rules + CLAUDE.md + hmw.js + adap-report + email + mark-proposal + HANDOFF = em-main · command .md + hook = restart-CLI/phiên-mới mới ăn (S27 + ENV-DEPENDENT S110) → pilot-checklist nằm HANDOFF NEXT-anh · HISTORY (session-log, archive verbatim, adap-report cũ, diary) GIỮ nguyên văn · script-RUN tay verify trong phiên ≠ hook-FIRE (phiên mới).

### Đường chết cần né
(X1) đụng `hmw-mode.on`/BƯỚC 0.5/`ultra-*` — HỆ KHÁC (HMW consent) · (X2) hook thêm content-gen/push/block-stop · (X3) add/commit đa-pathspec all-or-nothing · (X4) rewrite commit đã-push khi squash · (X5) claim hook "đang chạy" trước verify phiên mới (ghost-wire S100) · (X6) snapshot memory-pack · (X7) đổi code hmw.js (chỉ comment) · (X8) WAL append thay ghi-đè / vượt 40 dòng / chứa secret · (X9) commit script .sh trước khi .gitattributes có `*.sh` (n/a với .ps1 nhưng giữ thứ-tự: gitattributes trước) · (X10) renumber BƯỚC/§ cũ · (X11) tự stamp mark.

## Mục 3 — Checklist thực hiện

| # | Vai | Deliverable | Acceptance (đo được) |
|---|---|---|---|
| 1 | em-main | `.gitattributes` append `*.sh text eol=lf` (X9-first) + `.claude/WAL.md` template nguồn §2 | grep `*.sh text eol=lf` =1; `Test-Path .claude/WAL.md`=True; `(gc).Count` ≤40; check-ignore idiom → NOT-IGNORED |
| 2 | em-main | `.claude/settings.json` CREATE hooks-entry PS1 + STAGED-note trong engine | grep `"Stop"` =1; grep `wal-flush.ps1` =1; engine grep `STAGED-until-verified` ≥1 |
| 3 | worker-opus-1 (edit-direct, file MỚI) | `.claude/commands/pause.md` + `.claude/commands/tiep.md` (D3) | 2 file frontmatter `description:`; tiep grep "transcript"≥1(CẤM) + "ground-truth"≥1 + "wf:"≥1 + nhánh WAL-rỗng-dừng-sạch + "git status"≥1; pause grep "wal: pause"≥1 + "git add -A"≥1(CẤM-context) + trỏ /tiep |
| 4 | worker-opus-2 (edit-direct) | session-start.md BƯỚC 0.7 (D4) | grep "BƯỚC 0.7"=1; "CHỜ"≥1 vùng 0.7; git-diff KHÔNG chạm 0.5/0.5b/0.6/Phase-1+ |
| 5 | worker-opus-2 (edit-direct) | session-end.md §5.0 + §6.4 (D5) | grep "origin/main..HEAD"=1; "reset --soft"=1; "KHÔNG rewrite"≥1; "review-diff wal-paths"≥1; §6.4 sau 6.3 trước footer |
| 6 | worker-opus-3 (edit-direct, file MỚI) | `.claude/hooks/wal-flush.ps1` (D2 PS1-port) | lead chạy tay `powershell -ExecutionPolicy Bypass -File` exit-0 ×2 ca (có-delta → commit `wal:` thật; 0-delta → exit-0 im lặng); grep "exit 0"≥2 + try/catch; per-path loop + CAND; 0 push/content/block |
| 7 | worker-opus-3 (edit-direct) | workflows/README.md policy-flip :31+bảng + run.md template +`## taskList snapshot` (D6) | vùng :31 có "BẮT BUỘC" + "≥3"/"5 phút"; grep "taskList snapshot"≥1; mode-A vẫn hợp lệ cho fan-out nhỏ |
| 8 | em-main | engine PHẦN N + CAVEAT:402 + rules §5.2 + CLAUDE.md pointer (D7) | grep "PHẦN N"≥1; :402 có "ngoại-lệ"; rules grep "wal:"≥1; CLAUDE.md grep "/tiep"≥1; honest a-e đủ 5 trong PHẦN N |
| 9 | em-main | hmw.js :9/:19 comment-only (D8) | `node --check .claude/workflows/hmw.js` PASS; grep "OPTIONAL" :19 vùng = 0 (thay mandate-ref); git-diff hmw.js chỉ comment-line |
| 10 | em-main | WAL.md dogfood ghi-chain S111 + run.md update + adap-report + email AI_INFRA + mark-proposal (D9) | WAL chain ≥3 mục [x] bằng-chứng lệnh; report nêu ĐÚNG NẤC "khung dựng + STAGED + script-RUN-verified, hook-FIRE + pilot = phiên mới"; ACTIVE-MARKS CHƯA đổi; AskUserQuestion trình |
| 11 | reviewer-Fable (vai anh gán trong lệnh) | Cổng-cuối biên-test + sweep | fault-inject cây tạm: hook thiếu-1-path vẫn commit path-còn + exit-0; WAL >40-dòng bị bắt; /tiep WAL-rỗng dừng sạch; grep toàn-repo con-trỏ recovery = MỘT đường /tiep; honest a-e present; 0.5/hmw-mode/ultra-* untouched; spec-compliance từng row |
| 12 | em-main | HANDOFF pilot-checklist + restart-CLI note + STATUS blurb | NEXT-anh có: restart CLI · phiên mới verify hook-FIRE (git log `wal:`) · kill-giữa-chain → /tiep · đổi-acc · squash dry-run thật · pause-roundtrip 1 workflow THẬT |

**Map sàn-H22 → row:** ① sổ WAL ≤40/schema/ghi-đè → #1+#10 · ② hai tầng ghi (lead⟂hook persist-only 0-content fail-open per-path) → #2+#6+#8 · ③ /pause+/tiep 1-đường → #3+#11 · ④ delta mở/đóng (WAL-check · squash chưa-push · reset cuối) → #4+#5 · ⑤ WAL-workflow (snapshot args · wf: · harvest-liền · relaunch-cắt-gọt · mandate per-agent-file · trung-thực mất-mát) → #7+#8+#3(nhánh wf:) · honest (a)-(e) → #8+#10.