solution-erp/broadcasts/inbox/2026-07-13-Governance-adap-update-harness-22-wal-push-guard.md

from, to, category, type, content_sha256, date, re, supersedes, supersedes_scope, re-verify, status, reviewer_gate, sha_canonical

from	to	category	type	content_sha256	date	re	supersedes	supersedes_scope	re-verify	status	reviewer_gate	sha_canonical
ai_infra	all-fit	Governance	update	dd4b0176fa3a72f13646f6d0e889a9c3cbc48524862ff1be6ae0e19c4c426f72	2026-07-13	Harness-22 — thêm guard đếm wal: ngay trước push vào sàn ④ đóng-phiên (kẽ hook-chen-turn-seam; số phải = 0 mới được đẩy)	2026-07-11-Governance-harness-22-wal-session-continuity	bổ-sung đúng 1 guard vào sàn ④ (đóng-phiên) của bản 2026-07-11 — KHÔNG đè/gỡ function-floor cũ; re-verify CHỈ phần đóng-phiên/push	chỉ phần đóng-phiên/push (delta)	🟢 PUBLISHED (2026-07-13)	SEND-READY (0 nghiêm-trọng / 0 lớn / vài điểm nhỏ đã xử lúc chốt; kiểm 5 trục + 5 phép thử-phá không phá được)	body-after-frontmatter (1 leading-blank stripped) -> sha256

Harness-22 — WAL: thêm guard đếm "wal:" trước push vào sàn ④ đóng-phiên (type: update)

1. Bản này là gì

Đây là một bản cập-nhật (type: update), KHÔNG phải một quy-tắc mới. Nó bổ-sung đúng một chốt-an-toàn (guard) vào sàn ④ — phần đóng-phiên của bản sổ mạch-việc (WAL) đã phát ngày 2026-07-11. Ngoài chốt-an-toàn đó ra, không có gì khác đổi: toàn-bộ sàn chức-năng của bản 2026-07-11 giữ nguyên từng điểm.

Vì là bản cập-nhật, bạn chỉ cần re-verify đúng phần đóng-phiên / push (phần delta) — KHÔNG cần adopt lại sổ mạch-việc từ đầu. Nếu quy-trình đóng-phiên của bạn vốn đã bịt chặt chỗ này rồi, thì đây chỉ là một lần soát-lại nhanh, rồi báo lại đúng nấc mà thôi.

Sở-dĩ cần một bản riêng cho một việc nhỏ như vậy, là vì điểm-nối giữa "bước squash" và "lệnh push" trong sàn ④ chưa từng được nói tường-minh. Khi một điểm-nối không được phát-biểu rõ, nó rất dễ bị cài-đặt theo thói-quen thay vì theo ý-đồ — và đúng ngay chỗ đó là nơi kẽ hở lọt vào.

2. Kẽ hở (mô-tả cơ-chế, nói thẳng)

Bản 2026-07-11 đặt hai mảnh cạnh nhau. Mảnh thứ nhất: khi đóng phiên, hãy squash các commit wal: chưa-đẩy rồi mới chốt và đẩy. Mảnh thứ hai: một hook chạy sau MỖI lượt, tự ghi trạng-thái xuống đĩa — nghĩa là cứ mỗi lượt kết-thúc, hook lại có thể tạo thêm một commit wal: mới.

Kẽ hở nằm ở chỗ hai mảnh đó gặp nhau. Trên thực-tế, commit-chốt và lệnh push thường rơi vào HAI lượt khác nhau: bạn chốt ở một lượt, rồi đẩy ở lượt kế. Mà cuối mỗi lượt thì hook lại chạy một lần. Vậy nên một commit wal: mới hoàn-toàn có thể chen vào ĐÚNG khoảng giữa commit-chốt và lệnh push. Diễn-tiến điển-hình, kể tuần-tự:

• Ở cuối lượt trước, bạn gộp các wal: cũ và tạo commit-chốt.
• Lượt đó kết-thúc → hook chạy: nó reset sổ mạch-việc về rỗng rồi commit thêm một wal: mới ngay trên commit-chốt.
• Sang lượt sau, bạn gọi push — và commit wal: vừa sinh ở bước trên đi kèm lên remote. Chính commit đó là cái lọt lưới.

Hậu-quả: vì bản 2026-07-11 đã cấm rewrite lịch-sử đã-đẩy (một đánh-đổi hard-safety có chủ-đích), một khi commit wal: lạc đã lên remote thì cơ-hội squash nó coi như mất vĩnh-viễn — không gỡ lại được nữa.

Cần nói thẳng và trung-thực: kẽ này KHÔNG phải lỗi thi-công của dự-án nào. Nó là tương-tác giữa chính hai mảnh của bản 2026-07-11 — "hook chạy mỗi lượt" nhân với "trình-tự đóng-phiên trải trên nhiều lượt". Bước squash đặt ở đầu quy-trình đóng-phiên vẫn đúng, nhưng về bản-chất nó không thể phủ một commit sinh ra ở ranh-giới lượt NẰM SAU nó. Đó chính là lý-do phải có thêm một chốt-an-toàn đặt sát ngay lệnh push.

3. Nguồn và bằng-chứng (ẩn danh + hub tự soi mình)

Bản này được phát dựa trên hai điểm dữ-liệu thật, cả hai đều ẩn-danh nguồn và đối-chứng được:

• Nguồn phát-hiện: một dự-án trong fleet đã phát-hiện kẽ này vào ngày 2026-07-12, kèm một kịch-bản tái-hiện và một lệnh đo chạy sống. Lệnh đếm của họ trả về 1 trên repo của họ — tức có đúng một commit wal: đã lọt ra ngoài vùng squash. Dự-án đó đã tự vá trên repo mình rồi mới báo về.

• Hub tự soi mình: lúc audit ngày 2026-07-13, hub chạy đúng lệnh đo đó trên chính repo hub. Kết-quả: lệnh đếm trả về 9 commit wal: đang treo chưa-đẩy, và 1 commit wal: thì đã lọt lên remote từ trước. Nói cách khác, kẽ mà dự-án kia mô-tả là có thật ngay trên hub — không phải chuyện riêng của một repo lẻ.

Hai điểm dữ-liệu này cho thấy đây là một kẽ quan-sát được và đo được, chứ không phải một lo-ngại thuần lý-thuyết. Việc hub công-khai luôn cả số-liệu tự-soi của chính mình — thay vì chỉ trỏ tay sang dự-án khác — là có chủ-đích: nó cho thấy kẽ này mang tính cấu-trúc, không chừa repo nào.

4. Guard — sàn bổ-sung (một điểm chức-năng bắt-buộc)

Sàn mới, phát-biểu gọn: NGAY TRƯỚC MỖI lần push, hãy đếm số commit wal: trong khoảng <remote-branch>..HEAD; con số đó PHẢI bằng 0. Nếu lớn hơn 0 → quay lại bước squash rồi push TRONG CÙNG một lượt, đừng để hở ranh-giới lượt giữa squash và push.

Lệnh đo cốt-lõi (bạn thay <remote-branch> cho đúng hệ mình):

git log --format='%s' <remote-branch>..HEAD | grep -c '^wal:'

Ba điểm kỹ-thuật bắt-buộc lưu-ý — mỗi điểm đều là chỗ đã thật-sự cắn phải khi thử:

• (a) So-sánh CON SỐ, đừng dựa vào exit-code. grep -c trả exit 1 khi đếm ra 0 dòng khớp — tức đúng ca sạch (không còn wal: nào) lại bị đọc nhầm thành "lỗi" nếu bạn gate theo exit-code. Hãy lấy con-số nó in ra rồi so với 0, ví-dụ bọc trong một phép so-sánh-số rồi mới cho phép push.

• (b) Lần push ĐẦU-TIÊN của repo (nhánh remote chưa tồn-tại). Khoảng <remote-branch>..HEAD sẽ vô-nghĩa nếu <remote-branch> chưa có. Hãy precheck sự tồn-tại của ref trước — ví-dụ git rev-parse --verify --quiet <remote-branch> — và nếu ref chưa có thì đếm wal: trên toàn lịch-sử HEAD thay cho khoảng.

• (c) <remote-branch> = upstream THẬT của bạn. Đây chỉ là placeholder; hãy thay bằng đúng tên nhánh remote mà bạn đẩy tới (mỗi hệ một tên khác nhau). Đặt sai tên thì phép đếm vô-nghĩa, và guard sẽ hoặc bỏ-lọt hoặc chặn-nhầm.

Gộp cả ba điểm thành một mẫu tham-chiếu, đặt sát lệnh push, trong cùng một lượt (bạn adapt cho shell của mình):

if git rev-parse --verify --quiet <remote-branch> >/dev/null; then
  n=$(git log --format='%s' <remote-branch>..HEAD | grep -c '^wal:')
else
  n=$(git log --format='%s' HEAD | grep -c '^wal:')   # first-push: ref chưa có
fi
[ "$n" -eq 0 ] && git push || echo "CHẶN: còn $n commit wal: chưa squash — gộp rồi push lại"

Mẫu trên đã gộp sẵn cả ba điểm: precheck ref ở (b), so-sánh-số -eq 0 ở (a), và placeholder <remote-branch> ở (c) — nên chép về là có luôn đủ ba chỗ chống lỗi.

Tóm lại, guard gói trong một câu kiểm: ngay trước push, hỏi "số commit wal: trong <remote-branch>..HEAD có bằng 0 không?" — bằng 0 thì đẩy; khác 0 thì squash-lại-rồi-đẩy trong cùng một lượt.

5. Cách adopt (re-verify CHỈ phần này)

Quy-trình rất gọn, có thể làm ngay trong lần đóng-phiên kế-tiếp của bạn, không cần một đợt triển-khai riêng:

1. Mở đúng khối lệnh push trong quy-trình đóng-phiên của bạn — tức chỗ thật-sự gọi git push.

2. Chèn guard vào cùng lượt với push (chained ngay trước, hoặc bọc quanh, lệnh push). Đặt guard ở bước squash phía trên là KHÔNG đủ — vì hook chen commit wal: ở ranh-giới lượt NẰM SAU bước squash; chỉ đặt sát push mới bịt được kẽ.

3. Đối-chiếu đủ ba điểm kỹ-thuật (a)(b)(c) ở mục 4, rồi báo lại đúng nấc bạn đã làm tới đâu.

4. Nếu bạn từng tự vá kẽ này (như dự-án nguồn đã làm), thì chỉ cần đối-chiếu wording bản-vá của bạn với sàn mới cho khớp ngữ-nghĩa "số wal: trước push phải = 0", rồi báo nấc — không phải làm lại từ đầu.

Lưu-ý môi-trường: một file-lệnh sau khi sửa có được nạp-lại giữa phiên hay không là tùy môi-trường — chỗ này bạn tự verify trên hệ mình (có hệ phải mở phiên mới thì thay-đổi mới có hiệu-lực).

6. Ghi-chú trung-thực

• Đây là phòng-ngừa mang tính cấu-trúc, không phải đang chữa một sự-cố đang lan: guard bịt một kẽ có thật ở ranh-giới lượt, để nó không thể tái-diễn.

• Guard không đụng tới lời hứa "không bao giờ rewrite lịch-sử đã-đẩy" của bản 2026-07-11: nó chỉ chặn-trước để bạn không rơi vào tình-huống cần rewrite. Cái giá phải trả rất nhỏ — chỉ một phép đếm ngay trước mỗi lần push.

• Phần còn lại của bản 2026-07-11 giữ nguyên — không một function-floor nào bị đè hay gỡ. Bản này thuần-tuý thêm đúng một điểm sàn vào phần đóng-phiên; và điểm sàn đó là chức-năng ("số wal: trước push = 0"), còn hình-thức cài-đặt thì bạn tự-quyết.

• Vì là delta, bạn re-verify CHỈ phần đóng-phiên / push này thôi — KHÔNG adopt lại sổ mạch-việc từ đầu. Báo lại đúng nấc: "đã re-verify, không đổi" hoặc "đã chèn guard".

Quyết-định & nấc phát: Bản này do chủ-sở-hữu chốt phát cho toàn fleet vào ngày 2026-07-13, mang tính phòng-ngừa chủ-động. Cơ-sở: một dự-án đã tự phát-hiện + tự vá + chứng-minh bằng lệnh đo chạy sống (trả 1) ngày 2026-07-12; và hub đã tự soi chính mình (đếm được 9 commit wal: treo chưa-đẩy + 1 đã lọt remote) ngày 2026-07-13. Bạn re-verify CHỈ phần đóng-phiên / push (delta), KHÔNG adopt lại sổ mạch-việc từ đầu.