@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-kbnt-to-confluence/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: NTAPP-kbnt-to-confluence
+description: "Sinh và đồng bộ KBNT (Kịch bản nghiệm thu) của MỘT ĐỢT nghiệm thu lên Confluence — người dùng cuối thao tác và ký trực tiếp trên trang. Dò delta từ mốc đợt trước (git 6 repo + spec + demo_status), dò ảnh hưởng (ripple) để gom luồng E2E xuyên nhiều slice, fetch template KBNT từ Confluence, sinh case theo AC/DD (+KBKT nếu có), rồi tạo hoặc cập nhật trang đợt với merge giữ nguyên ô người dùng đã ký. Triggers: viết KBNT, kịch bản nghiệm thu, tạo đợt nghiệm thu, đẩy KBNT lên confluence, nghiệm thu ảnh hưởng, UAT script."
+user-invocable: true
+argument-hint: "\"<tên đợt>\" [--since YYYY-MM-DD] [--local]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Skill
+  - mcp__atlassian32__confluence_get_page
+  - mcp__atlassian32__confluence_get_page_children
+  - mcp__atlassian32__confluence_search
+  - mcp__atlassian32__confluence_create_page
+  - mcp__atlassian32__confluence_update_page
+  - mcp__atlassian__confluence_get_page
+  - mcp__atlassian__confluence_get_page_children
+  - mcp__atlassian__confluence_search
+  - mcp__atlassian__confluence_create_page
+  - mcp__atlassian__confluence_update_page
+---
+
+# NTAPP — KBNT → Confluence
+
+Sinh và đồng bộ **KBNT (Kịch bản nghiệm thu)** của **một đợt nghiệm thu** lên Confluence, theo template KBNT fetch từ Confluence. KBNT là tài liệu **người dùng cuối ký**, khác KBKT (kịch bản kiểm thử của QA) và khác KBNV/SRS (đặc tả yêu cầu) — xem `CONTEXT.md` mục *Acceptance documentation* của spec repo.
+
+## Nguyên tắc cốt lõi
+
+- **1 đợt = 1 trang.** Tên trang theo **convention của nhánh KBNT** đọc từ các trang con hiện có (ví dụ `KBNT - <nội dung đợt>`); nhánh rỗng thì dùng mặc định `KBNT — YYYY-MM — <tên đợt>`. Đợt do người dùng đặt tên, KHÔNG suy từ sprint/release. Gọi lại cùng tên đợt trong cùng tháng thì UPDATE trang đó; đợt khác thì CREATE trang khác. Trang đợt cũ đóng băng, không đụng lại.
+- **Trang là nơi có chữ ký — KHÔNG bao giờ ghi đè mù.** Publish lần 2 trở đi bắt buộc đọc trang live trước, merge theo mã case, giữ nguyên các ô người dùng đã điền. Parse bảng thất bại thì DỪNG, không ghi. Luật đầy đủ: `references/merge-rules.md`.
+- **Mã case bất biến.** `NT-<target>-<nn>` nằm trong ô đầu (`STT`) của dòng, cấp một chiều từ `case-registry.yaml`, không renumber, không tái sử dụng. Registry là ledger, không phải cache — mất là đứt truy vết. Trạng thái đúng bốn giá trị: `active` / `deferred` / `done` / `huy`.
+- **Case chưa làm được đi vào `kbnt-backlog.md`, không tan biến.** Đợt nào chốt dời case thì ghi case đó vào backlog kèm lý do và đợt cấp mã; đợt kế tiếp **đọc backlog ở bước dò nội dung** và mang case sang bằng đúng mã cũ. Nghiệm thu xong thì xóa khỏi backlog và đổi trạng thái registry thành `done`. Ledger đợt `kbnt-publish-history.md` phải **liệt kê ID target**, không chỉ đếm số — nếu không thì không tra được phần nào đã nghiệm thu.
+- **Chỉ đẩy bảng thông tin đầu tài liệu + bảng case lên Confluence.** Skill sinh hai file: bản đầy đủ (cảnh báo, chuẩn bị dữ liệu, phụ lục — giữ ở repo) và bản `{dot_slug}_kbnt_cases.md` chỉ chứa bảng case, là nguồn duy nhất để build storage. Hai khối đẩy lên đúng là bề mặt tick và ký của người dùng cuối; thêm nội dung khác vào chỉ làm loãng và tạo ra bản thứ hai phải merge. **Cột 2 của bảng thông tin là khối chữ ký** — publish lần 2+ carry nguyên văn từ snapshot (`--carry-info`), sinh lại là xoá chữ ký người phê duyệt.
+- **Không tự dời case.** Đánh dấu dời chỉ khi người dùng chốt rõ đúng case đó. Câu trả lời "chưa hiểu câu hỏi" là yêu cầu giải thích lại, KHÔNG phải đồng ý — suy diễn từ quyết định của case khác là làm case biến mất khỏi đợt mà không ai quyết.
+- **Đánh số mục bắt đầu từ A.** Hai mục đầu là `A` (cảnh báo) và `B` (chuẩn bị dữ liệu), hai phụ lục là `Phụ lục 1` / `Phụ lục 2`. Đừng đặt mục thân bài là `C`, `D` rồi phụ lục lại `A`, `B` — người đọc tưởng thiếu mục.
+- **Trang KBNT đã có trên Confluence là nguồn thứ tư, đọc TRƯỚC khi chốt phạm vi.** Git nói "đã làm gì", chỉ trang đã điền ô kết quả mới nói "đã nghiệm thu gì". `kbnt-publish-history.md` rỗng nghĩa là *skill* chưa chạy, KHÔNG nghĩa là chưa ai ký — đội thường đã viết KBNT tay nhiều đợt. Trang lạ thì backfill vào ledger. Bỏ bước này thì người dùng phải nghiệm thu lại thứ đã ký.
+- **Ô bảng phải bullet hóa, không viết dồn một dòng.** Dùng đúng ngưỡng đã chốt ở skill SRS: ô ≥ 2 câu và ≥ 80 ký tự → `<ul><li>`; `Các bước thực hiện` → `<ol><li>` bỏ tiền tố số; tầng kết quả → `<li><strong>Giao diện:</strong> …`; một `<li>` không gánh hai ý (tách cả vế sau dấu chấm phẩy). Kèm `<colgroup>` đặt bề rộng cột.
+- **Ô `Version tài liệu KBNV` của header chứa page-link tới các trang KBNV/SRS đã viết**, nhóm theo mục — map duyệt từ nhánh KBNV của dự án (header DD chỉ có lác đác dòng `Confluence SRS`, không đủ), ghi ở khối `tai_lieu_kbnv` của `dot-manifest.yaml`. Mục không tra ra chắc chắn thì bỏ trống, KHÔNG đoán.
+- **Header bảng tự viết, KHÔNG copy byte từ template.** PowerShell decode response Confluence thành Latin-1 khi thiếu `charset` → copy byte là dán mojibake lên trang; và template có thể tự lệch ô. Validator phải kiểm cả hàng header.
+- **Mục đã nghiệm thu ở đợt khác thì giữ hàng mục + nhãn ĐÃ NGHIỆM THU, chỉ bỏ hàng case.** Xoá hẳn làm số La Mã hụt và mất lý do. Danh sách mục cắt nằm trong `dot-manifest.yaml`, không hardcode trong script.
+- **Nhánh KBNT resolve một lần rồi cache vào `kbnt-branch.json` của dự án**, kèm convention tiêu đề đọc từ các trang con — đặt tên lệch convention làm trang mới trông như của dự án khác. CQL `title ~` xếp theo relevance và cắt theo `limit` nên KHÔNG đủ để kết luận "không có nhánh"; phải duyệt children. Nhánh KBNT hay nằm cạnh tài liệu yêu cầu, không nằm dưới nhánh Test.
+- **Nguồn hybrid:** AC (story Stage 5) + DD (Stage 4) là xương quyết định case nào tồn tại; KBKT (`{id}_detailed_test_manual_testcase.md`, `{id}_fixtures.yaml`) là thịt bổ sung dữ liệu và bước đã kiểm chứng. KBKT KHÔNG phải điều kiện bắt buộc.
+- **Soft gate per-target:** target thiếu DD hoặc thiếu story vẫn viết case, từ git diff + code + KBKT + mô tả người dùng, và đánh dấu `nguon: code-only` để review kỹ. Không chặn cả đợt vì một hotfix không có story.
+- **Case là việc người dùng cuối làm được và tự phán xử được.** CẤM case validate field-level (maxlength, required, format, tab-order) và case an toàn thông tin — những thứ đó thuộc KBKT. Unit backend không có màn thì ưu tiên diễn đạt qua bề mặt người dùng nhìn thấy; không có bề mặt nào thì vẫn viết case nhưng ghi rõ cần hỗ trợ kỹ thuật để kích hoạt.
+- **Kết quả mong đợi nêu đủ tầng hệ quả nhưng bằng lời nghiệp vụ** — nhãn `Giao diện:` / `Dữ liệu:` / `Gửi đi:` / `Log:` (đội gọi là "log", xem `terminology.md` của skill SRS), mỗi tầng một dòng, diễn đạt nghiệp vụ chứ không phải tên bảng/cột thô.
+- **Dữ liệu mô tả bằng đặc tính phân biệt, không bịa định danh.** "Một giao dịch của TCTC X ngày đối soát T-1, lệch số tiền, chưa từng gửi xử lý" là đúng; "một giao dịch lệch bất kỳ" là sai; bịa mã merchant cụ thể cũng sai.
+- **Nghiệm thu ảnh hưởng là mục bắt buộc xét, không phải tùy chọn.** Dò ripple cơ học rồi để người dùng tick, gom thành luồng E2E đặt tên theo nghiệp vụ.
+- **Mọi thao tác ghi Confluence DỪNG preview và chờ xác nhận.** Không đoán trang đích, không tự tạo nhánh KBNT khi không tìm thấy.
+- **Không hardcode host/pageId trong nội dung sinh ra.** Điểm vào cố định duy nhất là index dự án; mọi thứ khác resolve lúc chạy — `references/confluence-resolve.md`.
+
+## Instructions
+
+Đọc đầy đủ và làm theo: `./workflow.md`
+
+Tài liệu tham chiếu (đọc khi tới bước cần):
+- `./references/delta-detection.md` — dò nội dung đợt (4 nguồn, gồm cả trang KBNT đã có trên Confluence) + dò ripple để dựng luồng E2E.
+- `./references/kbnt-authoring.md` — **(đọc TRƯỚC khi viết case đầu tiên)** luật viết case: độ mịn, cách viết bước, kết quả mong đợi 4 tầng, dữ liệu, case cần hỗ trợ kỹ thuật, case hồi quy.
+- `./references/merge-rules.md` — **(bắt buộc cho bước publish lần 2+)** đọc lại trang, khớp mã case, so 3 chiều, khóa lạc quan, đánh dấu hủy.
+- `./references/confluence-resolve.md` — resolve host và trang cha, fetch template, storage format, cách publish.
+
+Script của skill (dùng thay vì viết lại tay — chính chỗ viết lại tay đã sinh ra lỗi font header và ô không bullet ở lần chạy đầu):
+- `./scripts/build-kbnt-storage.py --cases <…_kbnt_cases.md> --manifest <dot-manifest.yaml> --out <…storage.xhtml>` — build bảng case: header tự viết, `<colgroup>`, bullet hóa ô, cắt mục theo khối `da_nghiem_thu_o_dot_khac` của manifest, và tự chạy 3 phép kiểm (lệch cột kể cả hàng header / mojibake / số mục-case). Cần `pyyaml`.
+- `./scripts/confluence-create.ps1` — POST tạo trang mới (body > 150KB, MCP không tải nổi).
+- `./scripts/confluence-update.ps1` — PUT cập nhật trang, **có khóa lạc quan** (`-ExpectVersion`, lệch thì throw, không ghi).
+
+Tái dùng từ skill anh em (resolve đường dẫn lúc chạy bằng Glob, KHÔNG hardcode):
+- `**/NTAPP-srs-to-confluence/references/terminology.md` — từ điển thuật ngữ, giữ tiếng Anh cho `version` / `log` / `transaction`.
+- `**/NTAPP-srs-to-confluence/scripts/confluence-get.ps1` — đọc host `.32` bằng REST khi MCP `.32` chết.
+- `**/NTAPP-srs-to-confluence/scripts/confluence-publish.ps1` — PUT body bằng REST khi trang quá lớn cho MCP.
+- `**/NTAPP-dd-to-confluence/references/storage-format.md` — map Markdown sang storage format XHTML.

package/skills/NTAPP/.agent/skills/NTAPP-kbnt-to-confluence/references/confluence-resolve.md

@@ -0,0 +1,106 @@
+# Resolve Confluence: host, trang cha, template, publish
+
+---
+
+## 0. Hai host là hai instance riêng
+
+`10.254.136.32` (space `TTCN24`, MCP `mcp__atlassian32__*`) và `10.254.136.35` (space `TDOV`, MCP `mcp__atlassian__*`) là **hai Confluence khác nhau** — cùng một trang có pageId khác nhau ở hai bên, và pageId của bên này mở trên bên kia sẽ không ra (đã kiểm 2026-08-17 với `88716677`).
+
+Vì vậy:
+- **Điểm vào cố định là `.32` pageId `88716677`** (index các dự án). Luôn bắt đầu từ đây.
+- **Host đích không được giả định trước.** Trang dự án trong index có thể là child page của `.32`, cũng có thể chỉ là một **link** trỏ sang `.35`. Host của trang cha tìm được chính là host sẽ ghi.
+- Không tìm chéo: đã xác định host đích rồi thì mọi thao tác đọc/ghi trang đợt đi đúng MCP của host đó.
+
+**Đọc `.32` khi MCP `.32` chết (403 token hết hạn, tình trạng từ 2026-07):** resolve `confluence-get.ps1` của skill SRS bằng Glob rồi chạy:
+
+```bash
+powershell -ExecutionPolicy Bypass -File "<path>/confluence-get.ps1" -PageId 88716677
+```
+
+Exit khác 0 (chưa cấu hình credential, hoặc HTTP lỗi) → DỪNG, báo người dùng cấu hình `.confluence-auth`, không tự đi đường khác.
+
+## 1. Dò từ index tới nhánh KBNT
+
+**Resolve một lần rồi cache.** Nhánh KBNT của một dự án gần như không đổi. Dò được thì ghi `{kbnt_root}/kbnt-branch.json` (host, `space_key`, `parent_id`, tên nhánh, convention tiêu đề đọc từ các trang con) và lần sau dùng luôn. File này thuộc **dự án**, không thuộc skill — pageId tuyệt đối không được nằm trong file skill.
+
+### 1a. Hai cạm bẫy của `confluence_search`
+
+- **CQL `title ~ "..."` xếp theo relevance rồi cắt theo `limit`, không xếp theo cây.** Nhánh đúng có thể nằm ngoài 30 kết quả đầu trong khi các trang con của nó thì nằm trong. Đã dính thật: `title ~ "KBNT"` trong space đúng vẫn **không** trả về nhánh `9.2.4 KBNT`, chỉ trả các trang con và các trang KBNT của dự án khác cùng space. → CQL chỉ dùng để **bổ sung**, kết luận "không có nhánh KBNT" phải dựa trên **duyệt children**.
+- **Một space chứa nhiều dự án.** Trang tên rất giống nhau (`13.06. KBNT` vs `9.2.4 KBNT`) thuộc hai dự án khác hẳn. Luôn verify bằng `ancestors` xem trang có nằm dưới node dự án `{target_system_name}` không, đừng tin cái tên.
+
+### 1b. Đường phụ khi index `.32` chết cả hai lối
+
+MCP `.32` hết token (403) **và** `{auth_file}` không có block `CONFLUENCE_32_*` là tình huống thật, không phải giả định. Khi đó vẫn resolve được mà không cần đoán:
+
+1. Lấy một pageId **đã biết chắc thuộc dự án** — trang template KBNT, hoặc link `Confluence SRS:` trong header một DP bất kỳ của dự án.
+2. Trên host đích, `GET /rest/api/content/{id}?expand=ancestors` → được cả đường từ gốc space xuống, trong đó có node dự án.
+3. Từ node dự án duyệt children xuống nhánh KBNT.
+4. **Gọi REST bằng PowerShell `Invoke-RestMethod`.** `curl` của Git Bash đi qua proxy hệ thống và trả `403` HTML của Squid — nhìn giống hết hạn token nên rất dễ chẩn sai.
+5. Nhánh KBNT hay nằm dưới **tài liệu yêu cầu/thiết kế**, không nằm dưới nhánh **Test** (nhánh Test thường chỉ có KBKT + test plan + report). Đừng suy "có chữ Test thì KBNT ở đó".
+
+### 1c. Thủ tục gốc (khi index còn sống)
+
+1. Đọc index `.32` `88716677`:
+   - `confluence_get_page_children(parent_id=88716677, include_folders=true, limit=50)`, phân trang tới hết.
+   - Fallback: `get_page(page_id=88716677, convert_to_markdown=true)` rồi trích link trong body — một số dự án chỉ là link, không phải child page.
+2. Tìm dự án `{target_system_name}` (mặc định *Đối soát tập trung*). Không chắc hoặc nhiều ứng viên → **AskUserQuestion** liệt kê.
+3. Mở trang dự án theo đúng host của link. Từ đó dò xuống nhánh quản lý KBNT:
+   - Duyệt children nhiều tầng, hoặc `confluence_search` CQL `ancestor = <id trang dự án> AND (title ~ "nghiệm thu" OR title ~ "KBNT")`.
+   - Không thấy → **DỪNG hỏi người dùng chỉ nhánh**. Không tự tạo nhánh mới.
+4. Ghi nhớ `{parent_id}`, `{space_key}`, host — lưu vào `{dot_dir}/page-ref.json` để lần sau khỏi dò lại.
+
+## 2. Template
+
+- Tìm theo tiêu đề, không hardcode pageId: `confluence_search` CQL `space = TDOV AND title = "Template KBNT"` trên host `.35`.
+- `get_page(page_id, convert_to_markdown=false)` → parse thứ tự mục, tên mục, và **bộ cột của bảng case**.
+- Template nằm ở `.35` kể cả khi host đích là `.32` — đây là ngoại lệ đọc chéo duy nhất được phép, vì template chỉ cung cấp **khung**, không quyết định nơi ghi. Ghi rõ điều này ở preview.
+- Lưu khung parse được vào `{dot_dir}/template-snapshot.md`. Lần chạy sau, khung mới khác khung cũ → cảnh báo ở gate 2 (template đã đổi, các trang đợt cũ vẫn giữ khung cũ).
+
+## 3. Storage format
+
+Theo `storage-format.md` của skill `NTAPP-dd-to-confluence` (resolve bằng Glob). Điểm cần nhớ cho KBNT:
+
+- Escape `&`, `<`, `>` ngoài CDATA.
+- Xuống dòng trong ô bảng dùng `<br/>`, không dùng ký tự xuống dòng thật.
+
+### 3a. CẤM copy nguyên byte header của template — tự viết lại
+
+Hai lý do, đều đã làm vỡ trang thật (2026-08-18, `KBNT - Bàn giao tháng 8` v1):
+
+- **Double-encode.** `Invoke-RestMethod` của PowerShell 5.1 decode response **Latin-1** khi Confluence không khai `charset` trong `Content-Type`. Lưu lại là UTF-8 của chuỗi đã sai → header hiện `Mô tả trÆ°á»ng hợp` trên trang, trong khi body (build từ markdown local) vẫn đúng. Dấu hiệu chẩn đoán: **chỉ phần copy từ Confluence bị lỗi font, phần tự sinh thì không**. Nếu buộc phải đọc storage để phân tích thì lấy bytes rồi decode UTF-8 tường minh, đừng tin chuỗi PowerShell trả về.
+- **Template có thể tự sai.** Template KBNT lệch một ô ở hàng header 2 (span 5, đúng phải 4) và hàng 3 (span 11, đúng phải 10). Copy byte là bê luôn lỗi, và Confluence render lệch cột. Tự viết header theo **bảng cột trong `template-snapshot.md`** thì vừa đúng chính tả vừa đúng lưới.
+
+**Validator phải kiểm CẢ hàng header,** không chỉ hàng case: tổng `colspan` của hàng 1 = số cột; hàng 2 và 3 chỉ đếm phần **không** bị `rowspan` của hàng 1 phủ. Bỏ hàng header khỏi vòng kiểm là đúng cách để lỗi này lọt.
+
+### 3b. Bullet hóa nội dung ô — bắt buộc, theo rule đã chốt ở skill SRS
+
+Người dùng đã chốt hai lần ở `NTAPP-srs-to-confluence`: *"cần trình bày xuống dòng từng ý, có gạch đầu dòng rõ ràng, k viết chung 1 dòng gây khó nhìn"*. Bảng KBNT dùng **cùng** ngưỡng đó — nguồn: `**/NTAPP-srs-to-confluence/references/confluence-server-publish.md` và `srs-mapping.md`.
+
+| Cột | Cách trình bày |
+|:---|:---|
+| Mã case (`STT`) | text thuần |
+| `Mô tả trường hợp` | thường một câu → để nguyên; ≥ 2 câu **và** ≥ 80 ký tự → `<ul><li>` |
+| `Điều kiện` | `<ul><li>`, mỗi vế `<br>` gốc một `<li>`; vế mở đầu bằng nhãn (`Dữ liệu:`) → `<li><strong>Dữ liệu:</strong> …` |
+| `Các bước thực hiện` | **`<ol><li>`** (có thứ tự), **bỏ tiền tố `1.` `2.`** vì `<ol>` tự đánh số |
+| `Kết quả mong muốn` | `<ul><li><strong>Giao diện:</strong> …` — mỗi tầng hệ quả một `<li>` |
+| `Ghi chú` | như `Điều kiện` |
+| 10 ô kết quả | luôn `<br />` rỗng |
+
+Ngưỡng máy móc khỏi tranh luận: **≥ 2 câu VÀ ≥ 80 ký tự → bullet**; ô một câu hoặc ngắn thì để nguyên. Tách câu theo dấu chấm **và dấu chấm phẩy** — `;` trong tiếng Việt ngăn hai vế, và **một `<li>` không được gánh hai ý**. Vế còn ≥ 2 câu sau khi tách nhãn thì lồng `<ul>` cấp 2.
+
+Thêm `<colgroup>` đặt bề rộng từng cột. Không có nó, Confluence auto-size theo nội dung: cột `Mô tả trường hợp` bị bóp thành một chữ mỗi dòng khi các cột khác dài hơn.
+- Checkbox chọn được dùng `ac:task-list` với `ac:task-id` duy nhất toàn trang, không dùng ký tự ô vuông unicode.
+- Ngày dùng date macro `<time datetime="YYYY-MM-DD"/>` để ra chip lịch.
+- **Link sang trang Confluence khác dùng page-link theo tiêu đề**, không dùng `<a href>`: `<ac:link><ri:page ri:content-title="Tiêu đề trang" /></ac:link>` — Confluence tự render tên trang và tự theo khi trang bị di chuyển. Cùng space thì không cần `ri:space-key`. Tiêu đề phải **khớp tuyệt đối** (lấy từ `get_page_children` của nhánh thật, đừng gõ lại tay) và phải escape XML; sai một ký tự là ra link đỏ. Thẻ `<a href>` với URL `pageId` vẫn mở được nhưng hiện URL thô và chết khi đổi host.
+- **Không thêm mục ngoài template.** Cần chỗ ghi thứ template không có thì nêu ở gate 2 để người dùng quyết.
+
+## 4. Publish
+
+**Tiêu đề trang theo convention của nhánh, không theo khuôn skill.** Đọc tên các trang con hiện có trước khi đặt tên. Nhánh đã dùng `KBNT - <nội dung đợt>` thì theo dạng đó; chỉ nhánh rỗng mới dùng mặc định `KBNT — {YYYY-MM} — {tên đợt}`.
+
+- Mặc định đi MCP, body-only (KBNT không có attachment):
+  - CREATE: `confluence_create_page(space_key, title, content, parent_id, content_format="storage")`.
+  - UPDATE: `confluence_update_page(page_id, title, content, content_format="storage", is_minor_edit=false, version_comment="KBNT {tên đợt} — sync {ngày}")`.
+- Body lớn (khoảng trên 150KB — đợt nhiều case) làm MCP cắt output → đi REST. **UPDATE:** resolve `confluence-publish.ps1` của skill SRS bằng Glob, soạn manifest (pageId, baseUrl, title, storageFile, versionMessage, attachments rỗng), agent tự chạy. **CREATE:** script đó chỉ PUT trang đã có, nên phải tự `POST {base}/rest/api/content` với body JSON `{type:"page", title, space:{key}, ancestors:[{id}], body:{storage:{value, representation:"storage"}}}` — gửi bằng `Invoke-RestMethod` với bytes UTF-8, header `Authorization: Bearer <PAT>`.
+- Sau khi ghi, `get_page` lại và **đếm số hàng `<tr>`**: phải bằng `số hàng header + số mục + số case`. Kích thước byte trả về **to hơn bản gửi lên là bình thường** (Confluence tự re-encode ký tự thành entity), đừng coi đó là dấu hiệu lỗi. Thiếu `.confluence-auth` hoặc PAT còn placeholder → DỪNG hỏi người dùng, không publish một nửa.
+- Lỗi 401/403/404/409/timeout → DỪNG, báo nguyên nhân, **không retry sang host khác**. 409 nghĩa là version đã đổi — quay lại bước merge, không ép ghi.

package/skills/NTAPP/.agent/skills/NTAPP-kbnt-to-confluence/references/delta-detection.md

@@ -0,0 +1,96 @@
+# Dò nội dung đợt và dò ảnh hưởng
+
+Dùng ở §2 của `workflow.md`. Mục tiêu: từ mốc `{since}` ra hai danh sách — **target trực tiếp** (thứ vừa làm) và **ứng viên ảnh hưởng** (thứ có thể vỡ mà không ai đụng tới).
+
+Cả hai danh sách đều là **đề xuất**, không phải kết luận. Người dùng tick ở gate 1.
+
+---
+
+## 1. Target trực tiếp — hợp bốn nguồn
+
+### Nguồn A — code repo (bắt cả code chưa commit)
+
+Với mỗi code repo trong workspace (lấy từ file workspace hoặc thư mục cha của spec repo):
+
+```bash
+git -C "$repo" log --since="$since" --name-only --pretty=format:%H
+git -C "$repo" status --porcelain
+```
+
+Duyệt path bằng `while IFS= read -r` (path có dấu cách). Với mỗi file đổi, đọc **10 dòng đầu** tìm header `id: <ID>` do pre-commit Rule 1 bắt buộc, lấy `<ID>` làm unit.
+
+File không có header `id:` (file cũ, file config, file test) → **không bỏ im lặng**: gom thành danh sách "file đổi không map được unit" và trình ở gate 1 để người dùng gán tay hoặc bỏ qua. Đây là chỗ dễ sót nhất.
+
+### Nguồn B — spec repo
+
+- `{stage4_dir}/*_detailed_design.md` và `{stage5_dir}/*.md` có commit kể từ `{since}`, cộng file đang dirty theo `git status`.
+- ID lấy từ tên file (`BE-RA-13_detailed_design.md` → `BE-RA-13`; `E5-SCR-BC1-DETAIL-sent-audit-columns.md` → `SCR-BC1-DETAIL`).
+- DD đổi mà code không đổi vẫn là ứng viên hợp lệ: có thể spec đi trước, hoặc code nằm ở nhánh chưa merge.
+
+### Nguồn C — slice plan
+
+Slice trong `{slices_dir}` có `demo_status: passed` và chưa từng xuất hiện ở cột target của `{history}`.
+
+### Nguồn D — trang KBNT đã có trên Confluence (chống nghiệm thu hai lần)
+
+Ba nguồn trên trả lời "đợt này **đã làm** gì". Chúng KHÔNG trả lời "thứ đó **đã nghiệm thu** chưa" — và hai câu đó khác nhau, vì đội có thể đã viết KBNT tay từ lâu trước khi skill tồn tại. `{history}` rỗng chỉ nói skill chưa chạy, không nói chưa ai ký.
+
+Thủ tục, chạy cả khi `--local` vì hoàn toàn read-only:
+
+1. Liệt kê con của nhánh KBNT (`{branch_ref}`; chưa có thì dò theo `confluence-resolve.md` §1).
+2. Với mỗi trang đợt, đọc storage rồi rút bốn thứ: **tên trang**, **tên các mục chức năng** (hàng có ô thứ hai `colspan` lớn), **số dòng case**, và **số dòng case đã điền ô kết quả**.
+3. **Ô kết quả đã điền = đợt đó đã nghiệm thu.** Dấu hiệu chắc chắn nhất là ô "Mã giao dịch" có mã thật và ô "Kết quả" có ký hiệu đạt. Đừng suy từ tiêu đề hay từ ngày sửa trang.
+4. Đối chiếu **theo nghĩa nghiệp vụ**, không theo mã case — trang viết tay không có mã `NT-*` nào để khớp. So tên mục chức năng và mô tả trường hợp với danh sách target đang xét.
+5. Mỗi target trùng: ghi rõ **pageId nào phủ nó, phủ phần nào**, và đề xuất một trong ba — **bỏ khỏi đợt** (đã ký, không sửa gì thêm), **giữ làm case hồi quy** (đợt này sửa đúng vùng đó), hoặc **giữ nguyên** (trang cũ chỉ phủ một nhánh, phần còn lại chưa ai ký).
+
+Trang lạ chưa có trong `{history}` thì backfill vào ledger ở §11 của `workflow.md` — nếu không, đợt sau lại dò lại từ đầu và lại trùng.
+
+### Hợp và chuẩn hóa
+
+- Khử trùng theo ID.
+- Map unit → slice chứa nó (đọc slice plan) để nhóm hiển thị; **không** tự động kéo cả slice vào đợt chỉ vì một unit trong đó đổi.
+- Mỗi dòng ứng viên phải trả lời được: ID, tên, **tín hiệu nào phát hiện ra nó**, có DD không, có story không, có KBKT không, đã từng nghiệm thu ở đợt nào.
+
+---
+
+## 2. Ứng viên ảnh hưởng (ripple)
+
+Ba tín hiệu, chạy trên **tập file đã đổi** ở nguồn A.
+
+### 2.1 Seam code dùng chung
+
+Với mỗi file đổi, lấy tên class/hàm public bị sửa (đọc hunk), rồi tìm nơi khác gọi tới:
+
+```bash
+grep -rn "<TenClass>\|<tenHam>" --include=*.java --include=*.ts "$repo" | grep -v "<file da doi>"
+```
+
+Với mỗi file gọi tìm được, đọc header `id:` → unit khác chịu ảnh hưởng. Ví dụ thật của dự án: sửa `BaseMethod.createSshClient` chạm cả `BE-RP-01` lẫn `BE-RP-08`, dù chỉ commit vào một luồng.
+
+### 2.2 Tài nguyên chung
+
+Từ DD của target trực tiếp, trích các tài nguyên nó đọc/ghi: tên collection hoặc bảng, topic, endpoint, key cache, tên file trao đổi với đối tác. Rồi grep chính các tên đó trong **DD của các unit khác**:
+
+```bash
+grep -rln "<ten tai nguyen>" "{stage4_dir}"
+```
+
+Unit khác cùng ghi một tài nguyên là ứng viên ảnh hưởng mạnh nhất trong hệ đối soát — hai nguồn cùng ghi một bản ghi là nơi lỗi tiền hay xuất hiện.
+
+### 2.3 Phụ thuộc slice
+
+Đọc slice plan lấy quan hệ phụ thuộc giữa slice; slice phụ thuộc vào slice chứa target trực tiếp là ứng viên.
+
+### Trình bày
+
+Mỗi ứng viên ảnh hưởng phải có **bằng chứng đường dẫn file cụ thể**, không được chỉ nói "có liên quan". Ứng viên không nêu được bằng chứng thì không đưa vào danh sách.
+
+---
+
+## 3. Gom thành luồng E2E
+
+Ứng viên ảnh hưởng được người dùng giữ lại sẽ gom thành **luồng nghiệp vụ đặt tên**, không phải danh sách unit rời. Một luồng gồm: tên nghiệp vụ (do người dùng đặt), thứ tự các bước đi qua các unit, và điểm quan sát cuối cùng mà người dùng cuối kiểm được.
+
+Luồng không đặt được tên nghiệp vụ là dấu hiệu nhóm sai — hỏi lại người dùng thay vì tự đặt tên kỹ thuật kiểu "luồng BE-RP-01 + BE-RP-08".
+
+Mã target của luồng: `FLOW-<slug ngắn>` do người dùng chốt ở gate 1, dùng làm tiền tố mã case (`NT-FLOW-DOISOAT-T1-01`).

package/skills/NTAPP/.agent/skills/NTAPP-kbnt-to-confluence/references/kbnt-authoring.md

@@ -0,0 +1,128 @@
+# Luật viết case KBNT
+
+Đọc trước khi viết case đầu tiên. KBNT là tài liệu **người dùng cuối ký**, không phải bản sao của KBKT.
+
+---
+
+## 1. Luật cắt — case nào thuộc KBNT
+
+**Thuộc KBNT:**
+- Mỗi AC của story ít nhất một case đường thuận.
+- Nhánh **có hệ quả nghiệp vụ**: lệch và khớp, trùng, đối tác trả lỗi hoặc không phản hồi, quyền theo vai trò, dữ liệu biên ngày và cut-off, trạng thái không cho phép thao tác.
+- Hồi quy quanh vùng vừa sửa, khi target đã nghiệm thu ở đợt trước.
+- Luồng E2E của phần nghiệm thu ảnh hưởng.
+
+**KHÔNG thuộc KBNT (để KBKT lo):**
+- Validate field-level: bắt buộc, độ dài tối đa, định dạng, ký tự cấm, tab-order, focus, responsive.
+- An toàn thông tin: giả mạo request, SQL injection, IDOR, upload file độc.
+- Kiểm tra kỹ thuật thuần: có index chưa, log có đủ trường chưa, hiệu năng truy vấn.
+
+**Định lượng gợi ý:** 3 đến 8 case cho một unit, 5 đến 12 case cho một luồng E2E.
+
+Đây là **gợi ý mềm để phát hiện mình đang viết lệch**, KHÔNG phải giới hạn cứng của hệ thống:
+- Dưới 3 case cho một unit vừa sửa nhiều → khả năng bỏ sót nhánh có hệ quả nghiệp vụ.
+- Trên 8 case → khả năng đang viết case field-level hoặc chẻ một hành vi thành nhiều dòng.
+
+Vượt trần vẫn hợp lệ khi có lý do thật (ví dụ một menu mới thay hẳn hiện trạng làm tay). Khi vượt thì **nêu lý do ở gate 2, KHÔNG cắt case cho vừa trần** — cắt case để đẹp số là đánh đổi sai: mất một nhánh có hệ quả tiền còn tệ hơn một tài liệu dài.
+
+## 2. Cột và cách viết
+
+Bám **đúng bộ cột của template fetch được**. Ánh xạ nội dung vào cột theo nghĩa, không đổi tên cột của template.
+
+### Mã case (nằm trong ô đầu, thường là `STT`)
+
+`NT-<target>-<nn>`, ví dụ `NT-BE-RA-13-01`, `NT-SCR-BC1-DETAIL-04`, `NT-FLOW-DOISOAT-T1-02`. Cấp từ registry, không renumber. Thứ tự đọc do thứ tự dòng quyết định, không do số trong mã.
+
+### Mục đích
+
+Bắt đầu bằng "Kiểm tra" hoặc "Xác nhận", nêu rõ **đối tượng nghiệp vụ** và **khía cạnh** được nghiệm thu. Viết theo góc nhìn người dùng, không theo góc nhìn hàm.
+
+- Đúng: `Xác nhận giao dịch lệch số tiền sau khi gửi xử lý được ghi nhận người gửi và thời điểm gửi trên báo cáo chi tiết TCTC.`
+- Sai: `Kiểm tra API updateReconciliationAdjustments trả về 200.`
+
+### Tiền điều kiện
+
+Nêu trạng thái hệ thống và dữ liệu cần có trước khi bấm nút đầu tiên: người dùng đăng nhập với vai trò nào, dữ liệu ngày nào đã có, job nào đã chạy xong, file đối tác nào đã về.
+
+### Các bước thực hiện
+
+Chuỗi thao tác vật lý đầy đủ, mỗi bước một dòng, tách bằng `<br>` trong ô bảng: mở menu nào, lọc điều kiện gì, chọn dòng nào, bấm nút gì, xác nhận ở đâu.
+
+Cấm bước trống nghĩa kiểu "Quan sát", "Mở màn hình", "Kiểm tra kết quả" — phải nêu rõ mở màn nào, nhìn vùng nào.
+
+### Dữ liệu
+
+Mô tả bằng **đặc tính phân biệt đủ để tự tìm hoặc tự dựng**, không bịa định danh cụ thể, không nói trống.
+
+- Đúng: `Một giao dịch của TCTC X, ngày đối soát T-1, lệch số tiền giữa nội bộ và đối tác, chưa từng gửi xử lý.`
+- Sai vì trống: `Một giao dịch lệch bất kỳ.`
+- Sai vì bịa: `Giao dịch 00JKFQ66S2JWQANSG7A2026081B3 của merchant MC001.`
+
+Lấy dữ liệu theo thứ tự ưu tiên: `{id}_fixtures.yaml` của KBKT → ví dụ trong DD hoặc story → mô tả người dùng cung cấp. Không có thì ghi `[TBD]` và gom vào mục "Chuẩn bị dữ liệu và môi trường" ở đầu tài liệu.
+
+### Kết quả mong đợi
+
+Nêu **đủ mọi tầng hệ quả có thật** của case, mỗi tầng một dòng (`<br>` trong ô), nhãn tiếng Việt, nội dung diễn đạt nghiệp vụ:
+
+- `Giao diện:` cái người dùng thấy đổi trên màn.
+- `Dữ liệu:` bản ghi nghiệp vụ đổi thế nào — nói bằng tên nghiệp vụ, ví dụ "giao dịch chuyển trạng thái Đã gửi xử lý, ghi nhận người gửi và thời điểm gửi".
+- `Gửi đi:` thông điệp hoặc file đi ra hệ thống khác, nói bằng tên nghiệp vụ.
+- `Nhật ký:` dấu vết kiểm toán ghi lại được.
+
+Tên kỹ thuật (bảng, cột, topic) chỉ đặt trong ngoặc khi thực sự cần để đội hỗ trợ tra, không thay thế câu nghiệp vụ. Tầng nào case không tạo ra thì bỏ hẳn dòng đó, không ghi "không có".
+
+Chất lượng bắt buộc:
+- **Xác định:** một hành vi rõ ràng, cấm "chặn hoặc báo lỗi", cấm "A hoặc B".
+- **Loại trừ:** khẳng định cả cái phải xảy ra lẫn cái không được xảy ra khi dễ nhầm (ví dụ chỉ một thông báo, không kèm lỗi hệ thống).
+- **Không bịa chữ hiển thị:** thông báo trích nguyên văn từ nguồn (khóa i18n hoặc phần giao diện của DD); nguồn không có thì ghi `[TBD]`, không tự đặt câu chữ.
+
+### Ghi chú
+
+Dùng cho: đánh dấu case hồi quy, đánh dấu case cần hỗ trợ kỹ thuật, ghi target và nguồn (`code-only`), ghi liên kết tới đợt trước nếu là mã case cũ, và **tiền tố trạng thái** khi có.
+
+Hai tiền tố trạng thái, đặt ở **đầu** ô Ghi chú, đừng lẫn nhau:
+
+| Tiền tố | Nghĩa | Đợt sau |
+|:---|:---|:---|
+| `[Chưa nghiệm thu đợt này — dời đợt KBNT sau: <lý do>]` | còn nợ, phải quay lại | mang case sang, **xóa tiền tố**, dùng lại mã cũ |
+| `[Đã hủy — đợt <tên đợt>]` | bỏ vĩnh viễn | không mang sang, mã không tái sử dụng |
+
+**Chỉ đặt tiền tố dời khi người dùng chốt rõ đúng case đó.** Ba tình huống khác nhau, đừng gộp thành một:
+
+| Tình huống | Xử lý |
+|:---|:---|
+| Người dùng chốt không làm đợt này | tiền tố dời + ghi vào `kbnt-backlog.md` |
+| Giữ trong đợt, nhưng cần bản build có đủ mã | **không** tiền tố; nêu ở mục cảnh báo `A1` kèm danh sách case; thiếu mã thì để trống cột kết quả, KHÔNG đánh Không đạt |
+| Giữ trong đợt, nhưng chờ chốt nghiệp vụ | **không** tiền tố; `[TBD]` trong `Điều kiện` + một dòng ở mục `B3` |
+
+## 3. Case cho unit không có màn
+
+Thứ tự ưu tiên khi diễn đạt:
+
+1. **Bề mặt người dùng gián tiếp** — màn báo cáo hiển thị kết quả, màn quản lý file, file kết quả gửi đối tác, trạng thái bản ghi. Người dùng tự thao tác và tự phán xử.
+2. **Có hỗ trợ kỹ thuật** — khi không có bề mặt nào tự kích hoạt được. Khi đó case phải nêu rõ ba thứ: cách tạo kích thích (đẩy file mẫu, chờ job chạy theo lịch, gửi bản tin thử), ai làm phần đó, và **điểm quan sát mà người dùng cuối tự xác nhận được**. Ghi chú đánh dấu `Cần hỗ trợ kỹ thuật`.
+
+Không có điểm quan sát nào cho người dùng cuối thì case đó không phải KBNT — chuyển sang KBKT và nêu ở gate 2.
+
+## 4. Case luồng E2E (nghiệm thu ảnh hưởng)
+
+- Một case đi qua nhiều unit theo **thứ tự nghiệp vụ**, không phải theo thứ tự kỹ thuật.
+- Tiền điều kiện nêu đủ trạng thái đầu luồng; các bước nêu điểm chuyển giao giữa các chặng; kết quả mong đợi nêu điểm cuối cùng người dùng kiểm được, cộng các mốc trung gian quan sát được.
+- Mục đích của luồng phải nói rõ **cái gì có thể vỡ** do thay đổi của đợt này — đó là lý do luồng có mặt.
+
+## 5. Khung fallback (chỉ khi fetch template lỗi)
+
+Cảnh báo người dùng đang dùng fallback, rồi dùng khung này:
+
+1. Thông tin đợt nghiệm thu (tên đợt, phạm vi, ngày, người lập, phạm vi đẩy lên Confluence).
+2. **Mục A — Cảnh báo trước khi mở đợt** (`A1`, `A2`, …): thứ quyết định case nào ký được.
+3. **Mục B — Chuẩn bị dữ liệu và môi trường** (`B1`, `B2`, …): gom `[TBD]` theo nhóm người phải cấp.
+4. Danh sách chức năng nghiệm thu trong đợt.
+5. Kịch bản nghiệm thu theo chức năng — bảng: `STT (mã case) | Mục đích | Tiền điều kiện | Các bước thực hiện | Dữ liệu | Kết quả mong đợi | Kết quả thực tế | Đạt/Không đạt | Người nghiệm thu | Ngày | Ghi chú`.
+6. Kịch bản nghiệm thu ảnh hưởng (luồng E2E) — cùng bộ cột.
+7. **Phụ lục 1** — lệch giữa tài liệu và mã nguồn; **Phụ lục 2** — chi tiết `[TBD]` theo từng mục.
+8. Kết luận và ký duyệt, kèm dòng **bản build đã nghiệm thu**.
+
+**Đánh số bắt đầu từ A.** Hai mục đầu là `A`/`B`, hai phụ lục là `Phụ lục 1`/`Phụ lục 2`. Đừng đặt mục thân bài là `C`, `D` rồi phụ lục lại `A`, `B` — người đọc mở tài liệu sẽ tưởng thiếu hai mục đầu.
+
+**Chỉ mục 1 (bảng thông tin đầu tài liệu) và mục 5-6 (bảng case) được đẩy lên Confluence.** Phần còn lại là bản làm việc nội bộ.

package/skills/NTAPP/.agent/skills/NTAPP-kbnt-to-confluence/references/merge-rules.md

@@ -0,0 +1,113 @@
+# Merge với trang đã có chữ ký
+
+Áp dụng ở §8 và §10 của `workflow.md`. Đây là phần dễ mất dữ liệu nhất của skill: bốn ô mỗi dòng do **người dùng điền tay trên Confluence**, không tồn tại ở bản local.
+
+Quyết định nền và các phương án đã bác: `docs/adr/0014-kbnt-round-page-and-signed-cell-merge.md` của spec repo.
+
+---
+
+## 1. Phân loại ô
+
+| Nhóm | Ai là nguồn sự thật | Hành vi khi publish lại |
+|:---|:---|:---|
+| Mã case (ô đầu, `STT`) | Registry local | Khóa khớp dòng, không bao giờ sửa |
+| Nội dung case (mục đích, tiền điều kiện, các bước, dữ liệu, kết quả mong đợi) | Markdown local, **trừ khi bị sửa tay trên trang** | So ba chiều, mặc định giữ bản trên trang khi có sửa tay |
+| Kết quả thực tế, Đạt/Không đạt, Người nghiệm thu, Ngày | **Trang Confluence** | Giữ nguyên verbatim, tuyệt đối không sinh lại |
+| Cột 2 của **bảng thông tin đầu tài liệu** (Version KBNV / Ngày thực hiện / Người tạo / Người phê duyệt / Người thực hiện / Kết luận) | **Trang Confluence** | Khối chữ ký — carry nguyên văn từ snapshot (`--carry-info`), không sinh lại |
+| Ghi chú | Cả hai | Nối thêm phần mới, không xóa phần người dùng viết |
+
+Tên chính xác của bốn ô người dùng lấy từ **template fetch được** ở §3, không đoán. Không nhận diện được đủ bốn ô → DỪNG hỏi người dùng chỉ cột.
+
+## 2. Đọc và parse trang
+
+1. `confluence_get_page(page_id, convert_to_markdown=false)` lấy storage XHTML, ghi nhớ `version.number`.
+2. Parse từng bảng case: hàng tiêu đề để định vị chỉ số cột, các hàng còn lại thành bản ghi khóa bởi mã case ở ô đầu.
+3. **DỪNG, không ghi** khi gặp bất kỳ điều nào sau:
+   - Không tìm thấy bảng case nào.
+   - Có dòng mà ô đầu không phải mã case hợp lệ (người dùng chèn dòng tay).
+   - Mã case trùng nhau trong cùng trang.
+   - Số cột của một dòng lệch hàng tiêu đề.
+   Báo rõ dòng nào hỏng và đề nghị người dùng sửa trên trang, hoặc xác nhận cho phép bỏ qua dòng đó.
+
+## 3. So ba chiều
+
+Ba bản: `A` = snapshot lần publish trước (`{dot_dir}/last-published.snapshot.xhtml`), `B` = trang hiện tại, `C` = bản mới sinh từ markdown local.
+
+Với mỗi ô nội dung của một mã case:
+
+| A vs B | B vs C | Xử lý |
+|:---|:---|:---|
+| Giống (người dùng không sửa) | Khác | Lấy `C` — cập nhật bình thường |
+| Giống | Giống | Giữ nguyên |
+| Khác (người dùng đã sửa tay) | Khác | **Giữ `B`**, đưa vào danh sách xung đột để người dùng tick nếu muốn đè bằng `C` |
+| Khác | Giống | Giữ `B` |
+
+Không có snapshot `A` (đợt cũ, hoặc snapshot bị xóa) → coi như **mọi khác biệt đều là sửa tay**: giữ toàn bộ `B`, liệt kê khác biệt để người dùng chọn. An toàn trước, tiện sau.
+
+## 4. Case mới, case biến mất
+
+- **Case mới:** append cuối bảng của target tương ứng. Không chèn giữa, không sắp xếp lại bảng — thứ tự dòng là thứ tự người dùng đã quen.
+- **Case biến mất khỏi spec:** không xóa dòng. Thêm vào ô Ghi chú tiền tố `[Đã hủy — đợt {tên đợt}]` và giữ nguyên mọi ô khác. Dòng đã có kết quả ký thì càng phải giữ: đó là bằng chứng nghiệm thu.
+- **Case dời sang đợt sau:** cũng không xóa dòng, nhưng tiền tố **khác**: `[Chưa nghiệm thu đợt này — dời đợt KBNT sau: <lý do>]`. Phân biệt rõ với `[Đã hủy]` — hủy là bỏ vĩnh viễn, dời là còn nợ và phải quay lại. Case dời giữ nguyên các ô kết quả trống; đợt sau khi mang case này trở lại thì **xóa tiền tố**, không tạo dòng mới.
+- **Chỉ parse và chỉ ghi bảng case.** Trang có thể chứa nội dung khác do người trong đội thêm tay (ghi chú họp, ảnh chụp, bảng phụ). Những phần đó **giữ nguyên vị trí, không xóa, không sắp lại** — skill chỉ thay đúng bảng case.
+- **Target biến mất khỏi đợt:** giữ nguyên cả bảng của target đó, ghi chú ở đầu bảng.
+- **Mục bị cắt vì đã nghiệm thu ở đợt khác:** **giữ lại hàng mục**, thêm vào tên mục hậu tố `— **ĐÃ NGHIỆM THU** tại trang “{tên trang}” (pageId {id}). Không chạy lại trong đợt này.`, và **bỏ toàn bộ hàng case** của mục đó. Đừng xoá hẳn hàng mục: số La Mã sẽ hụt (`I, IV, V, …`) làm người đọc tưởng trang thiếu, và mất luôn lý do vì sao mục đó không có case. Case tương ứng chuyển `trang_thai: done` trong registry kèm `dot_da_ky` và `nghiem_thu_tai_page` — **không** xoá khỏi registry, vì mã case là bất biến.
+- **Danh sách mục bị cắt phải nằm trong `{dot_dir}/dot-manifest.yaml`** (khối `da_nghiem_thu_o_dot_khac`, khóa là số La Mã, giá trị là `page_id` + `page_title`) và bộ build storage **đọc từ đó**. Hardcode danh sách trong script tạm là mất tái lập: chạy lại là mất phần cắt, và không ai tra được ai quyết cắt cái gì.
+
+## 5. Khóa lạc quan
+
+Giữa lúc đọc trang (§8) và lúc ghi (§10) có thể có người vừa ký hoặc vừa sửa. Ngay trước khi ghi:
+
+1. `get_page` lại, so `version.number` với giá trị đã ghi nhớ.
+2. Khớp → ghi.
+3. Lệch → **hủy ghi**, không PUT. Đọc lại trang, chạy lại §8, trình lại preview. Không có ngoại lệ, không có cờ ép ghi.
+
+Ghi xong thì lưu `{dot_dir}/last-published.snapshot.xhtml` bằng **đúng nội dung vừa PUT**, và cập nhật `version` mới vào `page-ref.json`.
+
+## 6. Registry mã case
+
+`{kbnt_root}/case-registry.yaml`, một mục cho mỗi mã:
+
+Dạng **map theo mã** — khóa là mã case, nên không thể trùng khóa và tra được trực tiếp:
+
+```yaml
+NT-BE-RA-13-01:
+  target: BE-RA-13
+  muc: XIII                 # số La Mã của mục trong bảng case
+  dot_cap_ma: ban-giao-thang-8
+  muc_dich: "Xác nhận file kết quả gửi lại được sinh đúng ngày đối soát"
+  trang_thai: active        # active | deferred | done | huy
+  lan_dau: 2026-08-17
+NT-BE-RP-18-01:
+  target: BE-RP-18
+  muc: XI
+  dot_cap_ma: ban-giao-thang-8
+  muc_dich: "..."
+  trang_thai: deferred
+  lan_dau: 2026-08-17
+  ly_do_doi: "ACB chưa cấp mã bí mật bên gọi"
+NT-BE-RA-22-03:
+  target: BE-RA-22
+  muc: II
+  dot_cap_ma: ban-giao-thang-8
+  muc_dich: "..."
+  trang_thai: done
+  lan_dau: 2026-08-17
+  dot_da_ky: ban-giao-thang-8
+  hoi_quy: true
+```
+
+Bốn trạng thái:
+
+| `trang_thai` | Nghĩa | Có trong `kbnt-backlog.md`? |
+|:---|:---|:---|
+| `active` | đã đưa vào đợt đang chạy | không |
+| `deferred` | đã cấp mã, người dùng chốt **dời sang đợt sau** | **có** — kèm `ly_do_doi` |
+| `done` | đã nghiệm thu và ký xong | không — kèm `dot_da_ky` |
+| `huy` | bỏ hẳn; mã **không** tái sử dụng | không |
+
+Luật:
+- Cấp `nn` = số lớn nhất hiện có của target đó cộng một. **Không lấp chỗ trống** của mã đã hủy hay đã dời.
+- Case cũ xuất hiện lại ở đợt sau thì dùng lại mã cũ, không cấp mã mới; thêm `hoi_quy: true` nếu là case hồi quy.
+- Registry là ledger: không xóa mục, không đánh số lại, không sinh lại từ đầu. Mất registry thì mã đã ký trên các trang cũ hết truy vết được.
+- `deferred` và `done` là **cặp bù nhau với `kbnt-backlog.md`**: mỗi mã `deferred` phải có đúng một dòng trong backlog; đổi sang `done` thì đồng thời xóa dòng đó khỏi backlog. Lệch một trong hai chiều là case bị mất hoặc bị làm hai lần.