--- name: cat-luot description: Cắt một bản phạm vi (danh sách mã của đội sản phẩm, một khảo sát, hoặc Core của quét hình thái) thành các hàng của lộ trình kho theo sáu luật, kèm mục chờ điều kiện có lý do, việc vận hành của người thành mốc ngoài, và bảng phủ máy sinh — mọi mã ở đúng một chỗ. Dùng khi kho khai lo_trinh.tep và một đợt phạm vi mới tới: «cắt lượt», «đưa bản phạm vi vào lộ trình», «thêm đợt mới vào kế hoạch», «cắt Core thành hàng». KHÔNG dùng để mở vòng một hàng (đó là feature-loop), KHÔNG để ghi trạng thái vào tệp lộ trình, KHÔNG xếp điểm ưu tiên tự động. --- # Cắt lượt Biến một **bản phạm vi** thành các **hàng** của lộ trình kho (khoá `lo_trinh.tep` trong `_acceptance/config.yaml`), cùng các mục **chờ điều kiện** (khoá `chan_troi`) cho mã chưa cắt được và các **mốc ngoài** cho việc vận hành của người, rồi để **răng phủ** — một lệnh tất định, chỉ đọc — chứng rằng mọi mã nằm ở đúng một chỗ trong ba. Người gộp PR là người chốt. Lộ trình chỉ chứa việc PHÁT TRIỂN mà máy giao và chứng minh được (bước 2b). Kit (mã) không bao giờ ghi trạng thái vào tệp lộ trình: trạng thái từng hàng do máy suy từ hồ sơ và chỉ hiện trên trang lộ trình. Hàng và mục chờ điều kiện là Ý ĐỊNH — phiên ghi chúng vào tệp như mọi thay đổi người duyệt bằng PR. Gốc lệnh: `AG` là gốc gói acceptance-gate. Harness đặt `${CLAUDE_PLUGIN_ROOT}`; kho tự host kit đặt `AG=.` trước khi chạy. ## Bước 1 — có bản phạm vi trong git Bản phạm vi là MỘT tệp markdown theo khuôn `skills/acceptance/references/pham-vi-template.md` (đọc khuôn trước): ba khoá `dot` · `dang` · `nguon`, mỗi dòng `- \`\` — ` một mã. - Đội sản phẩm gửi văn bản tự do → chép từng mục thành một dòng mã, GIỮ mã gốc nếu văn bản có mã (`#7`, `KH1`, `R1m-2`); không có mã thì đánh mã ngắn theo nhóm (`A1`, `A2`, `B1`…). - Đầu vào là Core của quét hình thái (skill `morphological-scan`) → mỗi ô Core một mã `C1…Cn`; ô Later thành mã sẽ vào mục chờ điều kiện, ô Never vào `da_bac` của tệp lộ trình kèm lý do. - `dang`: `chuoi` khi các mục là một chuỗi tính năng nối nhau; `lan-va` khi là các lỗi, vá rời từ một khảo sát. Commit tệp này lên nhánh của lượt cắt. Răng từ chối bản phạm vi không có trong git — không có bản gốc thì không ai so được phủ. ## Bước 2 — đọc nhịp và lộ trình hiện có ```bash AG="${AG:-${CLAUDE_PLUGIN_ROOT}}" && node "$AG/scripts/cat-luot.mjs" --root . --nhip ``` Lệnh in trung vị số ngày từ lúc chốt phạm vi tới lúc ký Cổng Bằng chứng theo hạng, đo từ hồ sơ đã ký của kho. `n: 0` ở một hạng → KHÔNG đặt ngày cho hàng hạng ấy; để trống còn hơn bịa. Rồi đọc **đồng hồ cỡ** — bảng cỡ vòng → số lượt chấm → tỉ lệ chạm trần, đo lại từ chính hồ sơ của kho mỗi lần chạy (chỉ đọc, không ghi gì): ```bash AG="${AG:-${CLAUDE_PLUGIN_ROOT}}" && node "$AG/scripts/cat-luot.mjs" --root . --co ``` Bốn nhóm theo khối khoảng cỡ ở bước 3 (dưới mục tiêu · mục tiêu · cho phép · phải tách): `n_chot` là số vòng đã chốt phạm vi, `n` · `luot_tb` · `cham_tran_pt` đo trên vòng đã giao có lượt chấm, `it_du_lieu: true` khi `n` quá nhỏ để tin; `n_giu` là số vòng đã chốt mang dòng sổ «giữ cỡ — » (vòng giữ nguyên cỡ có tên ở Cổng Phạm vi — thẻ Cổng 1 đọc dòng ấy bằng cùng bộ đọc `scripts/co-hop-dong.cjs`). Đặt số đo cạnh khối khoảng: số của kho nói khác chính sách (nhóm «cho phép» chạm trần nhiều hơn nhóm «phải tách», hay nhóm mục tiêu không rẻ hơn) thì dán số đo của đồng hồ cỡ vào mô tả PR cắt lượt và báo chủ kit — KHÔNG sửa khối. Khoảng là chính sách của KIT, đi theo bản phát hành: ở kho tiêu thụ, SKILL này nằm trong bộ đệm plugin — sửa ở đó là mất ở lần cài sau và không ai thấy. Đồng hồ chỉ là đồng hồ. Thêm `--tu ` để chỉ đếm vòng chốt từ một ngày, `--lo-trinh ` để so cỡ khai lúc cắt (`tieu_chi`) với số tiêu chí thật của hợp đồng hàng đã mở (`du_kien`). Đọc tệp lộ trình hiện có: mã đã dùng (mã mới không trùng), hàng đã giao (hàng mới đứng trên dữ liệu thật của chúng), khối `moc` (mốc là ràng buộc ngày). ## Bước 2b — tách việc vận hành khỏi việc phát triển (trước sáu luật) Lộ trình chỉ chứa việc PHÁT TRIỂN mà máy giao và chứng minh được. Việc VẬN HÀNH là việc người làm ngoài sản phẩm — kết quả của nó là một hành động của người, không phải một hành vi của sản phẩm mà máy chứng được. Xếp từng mã theo năm luật dưới TRƯỚC khi cắt; chỉ mã phát triển đi tiếp vào sáu luật của bước 3. Mã «không làm» giữ luật cũ: mục chờ điều kiện có `ly_do`, hoặc `da_bac`. ``` 1. Mỗi mã xếp một trong ba: phát triển (máy giao và chứng được) · vận hành một lần · vận hành lặp lại. Người DÙNG một tính năng mà hàng khác giao cũng là vận hành (vd «trưởng phòng công bố OKR quý 4» khi «bấm Công bố» là một hàng): mốc ngoài, `hang` của mốc trỏ hàng tính năng. Lặp lại chỉ khi dòng mã tự nêu chu kỳ («mỗi quý», «mỗi kỳ») hay «mỗi tổ chức mới»; không nêu thì một lần. 2. Vận hành thành MỐC NGOÀI, không thành hàng: mục `moc` có `loai: ngoai`, `ai` (người làm — chép từ dòng mã; dòng không nêu người thì ghi «chủ kho» để người gộp PR sửa), `dot` (đợt đang cắt), `phu` (mã nó gánh), `ma` để hàng và mục chờ điều kiện nhắc tới, `ngay` nếu có hạn. Mốc ngoài được chờ hàng (`hang` của mốc = hàng phải giao trước mốc); chiều ngược lại thì không. 3. Không hàng nào đứng chờ mốc: `dung_tren` chỉ trỏ hàng. Hàng cần thứ một việc vận hành tạo ra: cần DỮ LIỆU thì theo luật 4; PHẠM VI chỉ biết sau việc vận hành (vd sửa danh sách góp ý sẽ gom) thì vào mục chờ điều kiện, `mo_lai_khi` nêu mốc. 4. Thiếu dữ liệu thật thì dùng dữ liệu giả có nhãn. Phép thử: hàng có tiêu chí đo trên dữ liệu mà một việc vận hành CHƯA xảy ra tạo ra (cập nhật tuần, câu hỏi thật, tệp thật của phòng ban) là thiếu dữ liệu thật; hàng chỉ cần thao tác của chính tính năng (tạo, bấm, giao, duyệt) thì không khai `du_lieu`. Rồi: (i) máy sinh từ khuôn dữ liệu thật, không viết tay — hàng sinh mang `du_lieu` = `sinh-gia` (phiên cắt TẠO hàng này khi bản phạm vi không có mã cho nó, `phu` rỗng); (ii) hàng đo trên nó mang `du_lieu` = `gia` và đứng TRỰC TIẾP trên hàng sinh; tiêu chí nào chỉ đo được trên dữ liệu thật thành ô bỏ qua có tên ở vòng của hàng ấy; (iii) thực tế vẫn là đồng hồ cuối — Cổng Giá trị đọc trên dữ liệu thật. 5. Vận hành LẶP LẠI thành mốc ngoài `lap` = `true` kèm đề xuất tự phục vụ. Lặp theo KỲ trong cùng tổ chức (mỗi quý) → một hàng tính năng tự phục vụ ngay. Lặp theo TỔ CHỨC hay KHO mới mà mới có một → một mục chờ điều kiện mở lại khi có cái thứ hai thật (phanh «không phổ quát quá sớm»: giữ ranh giới cấu hình và mã từ đầu, làm phần phổ quát khi có cái thứ hai). `tu_phuc_vu` trỏ mã hàng hoặc mục chờ điều kiện ấy. ``` ## Bước 3 — cắt theo sáu luật ``` 1. Mỗi hàng MỘT kết quả, câu giao (`cau_giao`) đúng một trong hai dáng: việc người dùng thấy → mở bằng vai (`vai`); việc nền → hành vi hệ thống đo được (`vai: nen` + `bat_khi`), không ép «Là kỹ sư…». 2. Hàng sau đứng trên dữ liệu thật của hàng trước — KẾT QUẢ thật của vòng trước đã giao, không phải dữ liệu vận hành; `dung_tren` chỉ trỏ hàng, và chỉ khi nó thật sự cần hàng trước đã giao. 3. Không chạm hai lớp khó đảo trong một hàng (dữ liệu người dùng, quyền, đăng nhập, tiền): tách thành hai hàng. 4. Cỡ hàng theo khoảng tiêu chí của khối CAT-LUOT-CO (`tieu_chi`): từ `tach_tu` thì tách, dưới mục tiêu thì xét gộp với hàng cùng nhóm. 5. Ngày rơi ra từ thứ tự và nhịp; hàng gắn mốc không được muộn hơn ngày mốc. 6. Mã không cắt được thành câu giao thì vào mục chờ điều kiện kèm lý do và điều kiện mở lại — không bỏ lặng. ``` **Khoảng cỡ** — chính sách của chủ kit, MỘT nguồn: răng đọc thẳng khối dưới đây, không số nào nằm trong mã. Khối chỉ đổi ở kho kit, cùng PR với số đo của đồng hồ cỡ làm căn cứ, và tới kho tiêu thụ qua bản phát hành (bước 2). ``` muc_tieu: 8-10 cho_phep_den: 12 tach_tu: 13 tran_luot_cham: 3 it_du_lieu_duoi: 10 ``` Mục tiêu 8–10 tiêu chí; 11–12 chỉ khi kết quả không tách được mà giữ nghĩa (ghi vì sao vào `ghi_chu`); từ 13 bắt buộc tách. Ước số tiêu chí của vòng hàng ấy sẽ mở — mỗi tiêu chí là một điều người duyệt kiểm được ở Cổng Bằng chứng — và ghi vào `tieu_chi`. Một câu giao gói hai, ba kết quả rời thì ước lớn và tách; nhiều mã cắt theo gốc kỹ thuật (bảng, khoá, hàng đợi) mà không mã nào tự giao được một kết quả thì gộp chúng vào hàng của kết quả chúng phục vụ. **Hai dáng câu giao:** - **Việc người dùng thấy** → câu MỞ bằng vai, nói người ấy làm gì và thấy gì: `"vai": "Trưởng phòng ban"`, `"cau_giao": "«Trưởng phòng ban mở trang OKR và thấy KR nào của đơn vị đang trễ»"`. - **Việc nền** (không có người dùng cuối — một răng, một bộ đọc, một hàng đợi) → hành vi hệ thống đo được, vai `nen`, ngưỡng đo ở `bat_khi`: `"vai": "nen"`, `"cau_giao": "«Lệnh đồng bộ chạy lại không nhân đôi bản ghi»"`, `"bat_khi": "Mười lượt chạy lại liên tiếp, số bản ghi không đổi"`. Không viết «Là kỹ sư, tôi muốn…» — việc nền không có người để đóng vai. Hai dáng cắt, theo `dang` của bản phạm vi: - **`chuoi`** — chuỗi tính năng: áp đủ sáu luật; `dung_tren` nối hàng theo dữ liệu thật. - **`lan-va`** — làn vá từ một khảo sát: gói mã theo màn hoặc vùng sản phẩm (một câu giao nói một màn chạy đúng); các hàng chạy song song nên KHÔNG đặt `dung_tren` giả giữa chúng; luật 1 hiểu là «một màn, một câu», luật 3 vẫn tách lớp khó đảo (một vá chạm đăng nhập thì thành hàng riêng, hạng T3). Mỗi hàng ghi theo khuôn `skills/acceptance/references/lo-trinh-template.json`: `ma`, `cau_giao`, `vi_sao`, `hang`, `dung_tren`, `bat_khi`, cộng năm trường của lượt cắt: `dot` (đúng `dot` của bản phạm vi), `phu` (danh sách mã bản phạm vi mà hàng gánh), `vai` (dáng câu giao), `tieu_chi` (cỡ dự kiến) và `du_lieu` (bước 2b luật 4, chỉ khi hàng sinh hay dùng dữ liệu giả). Việc vận hành vào khối `moc` theo bước 2b: `{ "ma", "ten", "ngay", "loai": "ngoai", "ai", "dot", "phu", "lap", "tu_phuc_vu", "hang" }`. Các trường này chỉ lượt cắt ghi và răng đọc — agent mở vòng làm từ hợp đồng, phép đo và kế hoạch của vòng, không đọc trường nào cho riêng nó từ lộ trình; đừng thêm trường cho agent. Mã chưa cắt được vào khối `chan_troi` cấp tệp: `{ "ma", "dot", "cau_giao", "ly_do", "phu", "mo_lai_khi" }`. Không ghi `trang_thai`, `pr`, `buoc_ke` — máy suy và vẽ chúng. ## Bước 4 — ghi hàng, chạy răng, rồi mới mở PR Thứ tự này có răng: ghi hàng → chạy răng → xanh mới mở PR. 1. **Ghi hàng**, mục chờ điều kiện và mốc ngoài vào tệp lộ trình, trên CÙNG nhánh với bản phạm vi, rồi commit. 2. **Chạy răng:** ```bash AG="${AG:-${CLAUDE_PLUGIN_ROOT}}" && node "$AG/scripts/cat-luot.mjs" --root . --pham-vi --lo-trinh ``` Thoát 0 → in bảng phủ (mỗi mã → hàng, mục chờ điều kiện hoặc mốc ngoài). Thoát 1 → mỗi dòng `lỗi:` nêu mã hoặc mốc — sửa rồi chạy lại; KHÔNG sửa bảng phủ bằng tay, bảng phủ là đầu ra của răng. Thoát 2 → tệp chưa vào git, bản phạm vi không đọc ra mã nào, hoặc khối khoảng cỡ của SKILL hỏng (thông điệp nêu khoá). Mốc của đợt mang mã mà không phải mốc ngoài, mốc ngoài thiếu `ai`, `lap` không phải true/false, hay mã ở `tu_phuc_vu` không có đều là `lỗi:`. Răng còn gắn cờ có tên — cỡ, dáng câu giao, vận hành, dữ liệu giả — dạng `hàng []: …` hay `mốc []: …`. Hàng ngoài đợt đang cắt không đổi mã thoát: mỗi cờ gom thành MỘT dòng `cảnh báo: [] hàng ngoài đợt …`. | cờ | khi | mức (hàng trong đợt) | |---|---|---| | `can-tach` | `tieu_chi` từ `tach_tu` | lỗi | | `tren-muc-tieu` | `tieu_chi` trên mục tiêu, tới `cho_phep_den` | cảnh báo | | `duoi-muc-tieu` | `tieu_chi` dưới mục tiêu; kèm «gộp được với …» khi hàng cùng `nhom` cũng dưới mục tiêu và tổng không quá `cho_phep_den` | cảnh báo | | `tieu-chi-sai-kieu` | `tieu_chi` không phải số nguyên dương | lỗi | | `chua-uoc-tieu-chi` | thiếu `tieu_chi` | cảnh báo | | `vai-khong-mo-cau` | câu giao không mở bằng `vai` đã khai | lỗi | | `nen-thieu-bat-khi` | `vai: nen` mà `bat_khi` rỗng | lỗi | | `chua-khai-dang-giao` | thiếu `vai` | cảnh báo | | `cho-van-hanh` | `dung_tren` trỏ `ma` hay `ten` của một mốc ngoài | lỗi | | `du-lieu-sai-gia-tri` | `du_lieu` khác `sinh-gia` và `gia` | lỗi | | `thieu-hang-sinh-gia` | `du_lieu: gia` mà không đứng trực tiếp trên hàng `sinh-gia` | lỗi | | `van-hanh-lap-chua-tu-phuc-vu` | mốc ngoài của đợt có `lap: true` mà chưa có `tu_phuc_vu` | cảnh báo | | `gan-moc-dang-chay` | gắn vào mốc phát hành đang chạy (ngày ≥ hôm nay, mốc đã có hàng ngoài đợt) — đổi đích chiến dịch giữa chừng | cảnh báo | Dòng `cảnh báo:` có hai loại; dòng `cua-dot` của khối dưới nhận ra loại thứ nhất: ``` cua-dot: ^cảnh báo: (hàng|mốc) .+? \[[a-z-]+\]: ngoai-dot: mọi dòng cảnh báo: còn lại ``` - **Của đợt đang cắt** (tên hàng hay mốc rồi `[]`) — gợi ý gộp, trên mục tiêu, chưa ước cỡ, chưa khai dáng, vận hành lặp lại: XỬ LÝ (gộp, khai, thêm tự phục vụ) hoặc giữ và ghi vì sao vào mô tả PR. - **Ngoài đợt** (mọi dòng `cảnh báo:` khác — dòng gom `[] hàng ngoài đợt …`, hàng cắt tay đời trước): chép vào mô tả PR, không sửa mục không thuộc lượt cắt. 3. **Xanh mới mở PR** — một PR cho cả đợt: bản phạm vi + hàng + mục chờ điều kiện. Dán bảng phủ của răng vào mô tả PR. Người gộp PR là người chốt lượt cắt (một chạm). Kho vẽ lại trang lộ trình trong cùng PR (`product-map.mjs`) nếu CI của kho chạy `--check`.