alp-code 0.9.0

package/skills/alp-plan/references/red-team-personas.md

@@ -0,0 +1,76 @@
+# Lăng kính rà đối kháng
+
+Bốn góc nhìn thù địch. Đọc **hết một lăng kính** rồi mới sang lăng kính kế tiếp — trộn lẫn
+thì cả bốn hội tụ về cùng một góc, và bài tập thành diễn.
+
+| Lăng kính | Tâm thế | Soi gì |
+|---|---|---|
+| **Kẻ tấn công** | như người muốn phá | vượt xác thực, injection, lộ dữ liệu, leo thang quyền, chuỗi cung ứng |
+| **Người phân tích failure** | định luật Murphy | race condition, mất dữ liệu, hỏng dây chuyền, thiếu đường phục hồi, rủi ro deploy, không có đường lùi |
+| **Kẻ phá giả định** | hoài nghi | phụ thuộc chưa nói ra, câu "cái này sẽ chạy" không có căn cứ, thiếu đường lỗi, giả định về quy mô và tích hợp |
+| **Người chỉ trích phạm vi** | thi hành YAGNI | over-engineering, trừu tượng hoá sớm, phức tạp không cần, thiếu bản tối thiểu, phạm vi phình, đánh bóng thừa |
+
+## Cách đọc theo một lăng kính
+
+Bạn đang rà **một tài liệu kế hoạch**, không phải code. Không có gì để lint, build hay
+test. Chỉ soi chất lượng kế hoạch.
+
+Luật khi rà:
+
+- **Cụ thể:** chỉ đúng phase nào, mục nào.
+- **Có kịch bản:** mô tả nó hỏng ra sao, với tình huống nào — không viết "có thể có vấn đề".
+- **Xếp mức:** CHẶN (chặn thành công) · NÊN SỬA (rủi ro đáng kể) · GHI NHẬN (đáng lưu ý).
+- **Bỏ chuyện vụn:** văn phong, đặt tên, định dạng.
+- **Không khen.** Không có câu "nhìn chung ổn". Chỉ phát hiện.
+- **5–10 phát hiện mỗi lăng kính.** Chất hơn lượng — danh sách 30 mục thì không ai xử lý.
+
+## Mẫu một phát hiện
+
+```markdown
+## Phát hiện {N}: {tiêu đề}
+- **Mức:** CHẶN | NÊN SỬA | GHI NHẬN
+- **Ở đâu:** Phase {X}, mục "{tên}"
+- **Sai gì:** {mô tả}
+- **Hỏng thế nào:** {kịch bản cụ thể — với input nào, tình huống nào}
+- **Bằng chứng:** {trích từ kế hoạch, hoặc chỉ ra chỗ THIẾU}
+- **Đề xuất:** {ngắn}
+```
+
+Ô **Bằng chứng** chấp nhận hai dạng: trích dẫn từ kế hoạch, hoặc chỉ ra thứ lẽ ra phải có
+mà không có. Dạng thứ hai thường là phát hiện giá trị nhất.
+
+## Mẫu phân xử
+
+```markdown
+## Phát hiện 1: {tiêu đề} — {MỨC}
+**Lăng kính:** {tên}
+**Ở đâu:** {phase/mục}
+**Sai gì:** {mô tả}
+**Hỏng thế nào:** {kịch bản}
+**Xử lý:** Nhận | Bác | Nhận có sửa
+**Lý do:** {cụ thể — "cảm thấy không quan trọng" không phải lý do}
+```
+
+## Mẫu mục ghi vào `plan.md`
+
+```markdown
+## Rà đối kháng
+
+### Lượt — {YYYY-MM-DD}
+**Phát hiện:** {tổng} ({nhận} nhận, {bác} bác)
+**Theo mức:** {n} CHẶN · {n} NÊN SỬA · {n} GHI NHẬN
+
+| # | Phát hiện | Mức | Xử lý | Áp vào |
+|---|---|---|---|---|
+| 1 | {tiêu đề} | CHẶN | Nhận | Phase 2 |
+```
+
+Mục này tồn tại để sáu tháng sau còn trả lời được: *"lúc đó đã biết rủi ro này chưa, và vì
+sao vẫn làm?"*
+
+## Giao đi thay vì tự rà
+
+Rủi ro cao thì giao cho một vai khác (`scripts/run-role.sh <vai>`) — vai có `alp-predict`,
+năm persona tranh luận, và quan trọng hơn: **nó không phải người viết kế hoạch**.
+
+Tự rà kế hoạch mình vừa viết luôn có điểm mù. Bốn lăng kính giúp giảm, không xoá được.

package/skills/alp-plan/references/red-team-workflow.md

@@ -0,0 +1,81 @@
+# Rà đối kháng kế hoạch
+
+Đọc kế hoạch với thái độ **thù địch**: mục tiêu là phá nó, không phải khen nó.
+
+Tâm thế: như thuê một người ghét người viết kế hoạch, trả tiền để họ tìm ra chỗ hỏng.
+
+## Hai đường chạy — chọn theo rủi ro
+
+### A. Giao đi một lượt phản biện độc lập — mặc định cho kế hoạch rủi ro cao
+
+```bash
+scripts/run-role.sh <vai>
+```
+
+Vai được giao có `alp-predict` (năm persona tranh luận) và `problem-solving`. Dùng nó thay
+vì tự phản biện chính kế hoạch mình vừa viết.
+
+Brief phải có: đường dẫn `plan.md` và các `phase-*.md`, quyết định nào đang cần chốt,
+ràng buộc nào không đổi được.
+
+**Phán quyết DỪNG nghĩa là thiết kế lại.** Không phải thêm một dòng "rủi ro đã
+biết" rồi đi tiếp.
+
+### B. Tự rà — khi việc nhỏ, hoặc không giao đi được
+
+Tự đọc kế hoạch qua từng lăng kính trong `red-team-personas.md`. Số lăng kính theo quy mô:
+
+| Số phase | Lăng kính |
+|---|---|
+| 1–2 | Kẻ tấn công bảo mật + Kẻ phá giả định |
+| 3–5 | thêm Người phân tích failure mode |
+| 6+ | thêm Người chỉ trích phạm vi |
+
+Đọc **hết một lăng kính** rồi mới sang lăng kính kế tiếp. Trộn lẫn thì cả bốn hội tụ về
+cùng một góc nhìn, và bài tập thành diễn.
+
+## Xử lý phát hiện
+
+1. **Gom** tất cả phát hiện.
+2. **Khử trùng lặp** mạnh tay — hai cách nói của cùng một vấn đề là một phát hiện.
+3. **Xếp** theo mức: CHẶN → NÊN SỬA → GHI NHẬN (cùng thang với `code-review`).
+4. **Cắt còn tối đa 15.** Danh sách 40 mục thì không ai xử lý, và mục quan trọng chìm mất.
+5. **Phân xử** từng phát hiện: nhận hay bác — **kèm lý do có bằng chứng**. "Cảm thấy không
+   quan trọng" không phải lý do.
+
+## Hỏi principal
+
+Trình bày gọn:
+
+- Tổng số phát hiện theo mức.
+- Phát hiện nào bạn đề nghị nhận, phát hiện nào bác — kèm lý do.
+- Hỏi: áp dụng hết phần đề nghị nhận, xem từng cái, hay bác tất cả?
+
+**Không tự sửa kế hoạch trước khi principal quyết.** Kế hoạch là hợp đồng đã trình; sửa
+lặng lẽ nghĩa là principal duyệt một bản, còn thực thi theo bản khác.
+
+## Áp dụng
+
+Principal duyệt rồi mới sửa. Với mỗi phát hiện được nhận:
+
+- Sửa thẳng vào `phase-*.md` liên quan.
+- Thêm mục `## Rà đối kháng` vào `plan.md`: phát hiện, mức, xử lý (nhận/bác/nhận có sửa),
+  lý do.
+
+Mục đó tồn tại để sáu tháng sau còn trả lời được câu "sao lúc đó biết rủi ro này mà vẫn làm?".
+
+## Báo cáo
+
+```
+Rà đối kháng: <đường dẫn kế hoạch>
+Đường chạy: giao đi | tự rà
+Phát hiện: CHẶN n · NÊN SỬA n · GHI NHẬN n
+Nhận: n · Bác: n
+File đã sửa: <danh sách>
+Rủi ro đã xử lý: <tóm tắt>
+Câu hỏi còn mở: …
+```
+
+## Bước sau
+
+Chạy `validate-workflow.md`. Xong thì báo principal — **không tự bắt tay triển khai**.

package/skills/alp-plan/references/research-phase.md

@@ -0,0 +1,57 @@
+# Pha thu thập bối cảnh
+
+**Bỏ qua khi:** principal đã đưa sẵn report, hoặc việc quá nhỏ.
+
+Nguyên tắc: **đừng tự đọc hết**. Giao cho vai chuyên môn, gom kết quả, kiểm chứng trước
+khi tin. Đó vừa là lý do các vai chuyên môn tồn tại, vừa là cách giữ context của bạn sạch
+— compiled policy invariants giới hạn boot set ≤ 7 nguồn.
+
+## Giao cho ai
+
+| Cần gì | Giao cho vai chuyên |
+|---|---|
+| code hiện tại nằm đâu, ai gọi ai, đổi thì vỡ đâu | truy xuất code trong repo |
+| thư viện/framework bên ngoài, cách làm đang là chuẩn | nghiên cứu nguồn ngoài |
+| đã từng quyết định gì, thread nào còn hiệu lực | truy xuất trí nhớ |
+| phản biện một thiết kế rủi ro cao | phản biện độc lập |
+
+Ai đảm nhận vai nào: `src/agents/registry.ts` và `delegates_to` trong loadout của bạn.
+Lệnh: `alp delegate <vai> "<task>"`; `scripts/run-role.sh <vai>` là facade compatibility.
+
+Ba việc đầu **độc lập với nhau** → giao background và theo dõi bằng
+`alp delegation status|wait`; execution nền do supervisor giữ nên nó sống lâu hơn lệnh `alp`.
+
+## Viết brief cho vai được giao
+
+Delegation API mở một **execution riêng**. Nó chỉ thấy context ALP đã build, không thấy toàn
+bộ context phiên của bạn. Brief thiếu thì nó đi hỏi lại, hoặc tệ hơn — tự đoán.
+
+Brief tối thiểu phải có:
+
+1. **Câu hỏi kiểm chứng được**, không phải chủ đề. "Tìm hiểu auth" là chủ đề. "Chỗ nào
+   trong `src/` gọi `verifyToken`, và có chỗ nào bỏ qua kiểm hạn không" là câu hỏi.
+2. **Ranh giới** — thư mục nào, repo nào, tới đâu thì dừng.
+3. **Dạng kết quả mong muốn** — danh sách `path:line`, bảng so sánh, hay một kết luận.
+4. **Ngân sách** nếu muốn giới hạn (một lượt nghiên cứu mặc định tối đa 5 lượt tìm).
+
+## Tự làm phần nào
+
+Có vài thứ giao đi tốn hơn tự làm:
+
+- **Đọc GitHub:** `gh pr view`, `gh run view --log` — có `Bash` thì làm trực tiếp nhanh hơn.
+- **Xem repo ngoài:** `npx repomix --remote <url>` cho một bản tóm tắt. Nhớ chạy
+  `--token-count-tree` trước để không kéo về thứ vượt context.
+
+## Gom kết quả
+
+- **Không dán nguyên báo cáo của vai khác vào plan.** Rút phần dùng được, dẫn nguồn.
+- Hai vai nói ngược nhau → nói rõ trong plan, đừng chọn hộ một cách âm thầm.
+- Vai nào ghi "chưa chắc" thì phần đó vào mục **Câu hỏi còn mở** của plan, không được lặng
+  lẽ thành sự thật.
+
+## Quy tắc
+
+- Rộng trước, sâu sau. Đào sâu một hướng khi chưa biết có mấy hướng là cách chốt nhầm.
+- Tìm ít nhất hai cách tiếp cận để so — một phương án duy nhất thì không phải lựa chọn.
+- Ghi lại phát hiện đủ để pha thiết kế dùng lại được, không phải đọc lại từ đầu.
+- Vấn đề bảo mật ghi ngay khi thấy, đừng để tới pha review.

package/skills/alp-plan/references/scope-challenge.md

@@ -0,0 +1,82 @@
+# Bước 0 — thách thức phạm vi
+
+Chạy **trước** khi thu thập bối cảnh hay thiết kế. Ép làm rõ ý định trước khi đổ thời gian
+vào một kế hoạch sai cỡ.
+
+Đây là bước rẻ nhất và hay bị bỏ nhất. Một câu hỏi ở đây tiết kiệm cả một pha thu thập.
+
+## Bỏ qua khi
+
+- Việc nhỏ rõ ràng: sửa một file, sửa chính tả, đổi config không có nhánh logic.
+- Principal nói "cứ lập nhanh thôi" hoặc có tín hiệu gấp.
+- Mô tả dưới 20 từ và không mơ hồ.
+
+## Ba câu hỏi
+
+### 1. Cái gì đã có sẵn?
+
+Quét repo tìm code đã giải một phần bài toán. Tiện ích, module, mẫu nào dùng lại được.
+
+alp-code có nguyên tắc thành văn cho chuyện này — `README.md`: `scripts/lib/` là "MỘT nguồn
+cho mỗi loại config". Kế hoạch dựng thêm một nguồn thứ hai cho cùng loại dữ liệu là kế
+hoạch sai, không phải kế hoạch lớn.
+
+Không chắc → giao đi một lượt truy xuất code trước khi trả lời.
+
+### 2. Tập thay đổi tối thiểu là gì?
+
+Phần nào hoãn được mà không chặn mục tiêu lõi? Phũ với chính mình ở đây: cái "tiện thì làm
+luôn" đội lốt yêu cầu là dạng phình phạm vi khó thấy nhất.
+
+Đây chính là YAGNI, áp dụng cho kế hoạch trước khi áp dụng cho code.
+
+### 3. Kiểm tra độ phức tạp
+
+| Ngưỡng | Phải làm gì |
+|---|---|
+| đụng **> 8 file** | thách thức: cùng mục tiêu đó làm với ít file hơn được không? |
+| thêm **> 2 module/lớp mới** | mùi. Biện minh từng cái, hoặc bỏ |
+| **> 3 phase** | xem có gộp phase được không |
+
+Vượt ngưỡng không có nghĩa là sai. Nó có nghĩa là **phải giải thích được**, và lời giải
+thích đi vào `plan.md`.
+
+## Chốt phạm vi với principal
+
+Hỏi thẳng trong phiên, không cần tool nào.
+
+Trình bày kết quả ba câu trên rồi hỏi chọn một trong ba hướng:
+
+| Hướng | Nghĩa |
+|---|---|
+| **MỞ RỘNG** | làm bản đầy đủ — nghiên cứu sâu, khám phá phương án lân cận, chấp nhận nhiều phase |
+| **GIỮ NGUYÊN** | phạm vi đang đúng — dồn sức vào failure mode, edge case, tiêu chí kiểm chứng |
+| **THU HẸP** | cắt còn cốt lõi — hoãn mọi thứ không chặn, ít phase, kiến trúc đơn giản |
+
+## Luật quan trọng nhất
+
+**Principal chọn rồi thì TÔN TRỌNG.**
+
+Không được:
+
+- Âm thầm thu hẹp khi principal chọn GIỮ NGUYÊN hoặc MỞ RỘNG.
+- Âm thầm mở rộng khi principal chọn THU HẸP.
+- Cãi lại về phạm vi ở các mục sau của kế hoạch.
+
+Nêu lo ngại về phạm vi **một lần**, ở bước 0. Sau đó cam kết với phạm vi đã chọn và tối ưu
+bên trong nó. Đây cũng là HOUSE-RULES §1.7: cắt giảm phạm vi là quyền của principal.
+
+## Đầu ra
+
+Trước khi sang bước tiếp, xuất tóm tắt ngắn:
+
+```
+Thách thức phạm vi:
+- Đã có sẵn: <cái gì dùng lại được>
+- Tối thiểu: <cái gì thiết yếu, cái gì hoãn được>
+- Độ phức tạp: <ước lượng số file, module mới>
+- Hướng đã chốt: MỞ RỘNG | GIỮ NGUYÊN | THU HẸP
+```
+
+Phần "hoãn được" đi thẳng vào mục **Ngoài phạm vi** của `plan.md` — đừng để nó chỉ tồn tại
+trong context của phiên này.

package/skills/alp-plan/references/solution-design.md

@@ -0,0 +1,76 @@
+# Thiết kế giải pháp
+
+## Nguyên tắc nền
+
+**YAGNI** — không thêm cho tới khi thật sự cần.
+**KISS** — chọn cách đơn giản, kể cả khi cách phức tạp trông thông minh hơn.
+**DRY** — không nhân bản. Nhân bản dữ liệu rồi để nó lệch nhau là dạng nợ đắt nhất.
+
+Ba nguyên tắc này là luật thành văn của repo, không phải khuyến nghị.
+
+## So sánh phương án
+
+**Một phương án duy nhất không phải lựa chọn.** Nêu ít nhất hai, kèm bảng:
+
+| Phương án | Hợp khi | Đánh đổi | Chi phí đảo ngược |
+|---|---|---|---|
+| A | … | … | … |
+| B | … | … | … |
+
+Cột **chi phí đảo ngược** quan trọng nhất và hay bị bỏ: một quyết định sai mà đảo lại rẻ
+thì cứ chọn và đi tiếp; một quyết định sai mà đảo lại đắt thì đáng mở một lượt phản biện
+trước.
+
+Cân: ngắn hạn và dài hạn · độ phức tạp và khả năng bảo trì · công sức và lợi ích thật.
+
+## Bảo mật — nghĩ ở pha thiết kế, không để tới pha review
+
+- Ai được làm gì, kiểm ở đâu.
+- Dữ liệu nhạy cảm đi qua đâu, lưu ở đâu, ai đọc được.
+- Input từ ngoài được kiểm ở ranh giới nào.
+- Secret quản lý thế nào — biến môi trường, không phải file trong repo.
+- Với API: giới hạn tần suất, CORS, xác thực.
+
+Lỗ bảo mật phát hiện lúc thiết kế tốn một dòng sửa trong plan. Phát hiện sau khi triển
+khai tốn một phase.
+
+## Hiệu năng và quy mô
+
+- Nút thắt tiềm tàng nằm ở đâu — nói cụ thể, không nói "cần tối ưu".
+- Truy vấn nào có nguy cơ N+1.
+- Chỗ nào đáng cache, và cache mất hiệu lực khi nào.
+- Tài nguyên: bộ nhớ, CPU, mạng.
+
+**Quy mô thật của alp-code là 8 vai và một principal.** Thiết kế cho hàng trăm agent là
+over-engineering ở đây. Dùng `alp-predict` hoặc kỹ thuật quy mô của `problem-solving` để
+kiểm cả chiều nhỏ, không chỉ chiều lớn.
+
+## Edge case và failure mode
+
+Phase nào không nêu được failure mode thì **chưa duyệt được**. Bắt buộc trả lời:
+
+- Hỏng ở đâu, và hỏng thì lan tới đâu?
+- Hỏng một phần thì trạng thái còn nhất quán không?
+- Có cần retry / fallback không? Retry có gây hại gì không?
+- Có race condition không?
+- Xuống cấp có kiểm soát trông như thế nào?
+
+alp-code chọn **fail đóng**: hỏng thì hỏng to và thấy ngay. Thiết kế nào hỏng im lặng là
+thiết kế sai ở repo này — compiled policy invariants và cả `doctor.cjs` đều dựng trên nguyên tắc đó.
+
+## Kiến trúc
+
+- Ranh giới module: cái gì thuộc về đâu, và **vì sao**.
+- Chiều phụ thuộc: ai được biết về ai. Phụ thuộc vòng là dấu hiệu ranh giới sai.
+- Dòng dữ liệu: vào đâu, biến đổi ở đâu, ra đâu.
+- Cái gì là **nguồn sự thật**, cái gì là **sản phẩm sinh ra**. Nhầm hai loại này là lớp
+  bug đắt nhất trong alp-code — `compiled AgentDefinition` là nguồn, `~/.alp/executions/**` là sản phẩm.
+- Trạng thái giữ ở đâu, và ai được sửa.
+
+## Quy tắc
+
+- **Ghi lý do quyết định**, không chỉ ghi quyết định. Sáu tháng sau `git log` cho biết đã
+  làm gì; chỉ plan mới cho biết vì sao.
+- Thiết kế kèm cách kiểm chứng — không kiểm được thì không đóng được phase.
+- Nghĩ tới cả cách quan sát lúc chạy: hỏng thì nhìn vào đâu để biết.
+- Nghĩ tới cách quay lui: triển khai xong mà sai thì lùi bằng cách nào.

package/skills/alp-plan/references/validate-question-framework.md

@@ -0,0 +1,89 @@
+# Khung câu hỏi kiểm chứng
+
+## Nhóm câu hỏi
+
+Quét kế hoạch tìm những từ này — chúng đánh dấu chỗ kế hoạch đang **quyết thay principal**:
+
+| Nhóm | Từ khoá cần soi |
+|---|---|
+| **Kiến trúc** | "cách tiếp cận", "mẫu", "thiết kế", "cấu trúc", "database", "API" |
+| **Giả định** | "giả sử", "kỳ vọng", "sẽ", "phải", "mặc định" |
+| **Đánh đổi** | "đánh đổi", "so với", "phương án", "hoặc" |
+| **Rủi ro** | "rủi ro", "có thể hỏng", "phụ thuộc", "chặn", "lo ngại" |
+| **Phạm vi** | "phase", "bản tối thiểu", "sau này", "ngoài phạm vi", "có thì tốt" |
+
+Từ **"mặc định"** và **"giả sử"** đáng soi nhất: chúng thường đánh dấu một quyết định đã
+được đưa ra mà không ai để ý là đã có quyết định.
+
+## Luật soạn câu hỏi
+
+- Mỗi câu **2–4 phương án cụ thể**, không hỏi mở.
+- Đánh dấu phương án bạn đề nghị, kèm một câu vì sao.
+- Câu hỏi phải làm **lộ ra một quyết định ngầm**, không phải hỏi cho có.
+- **Chỉ hỏi điểm quyết định thật.** Tự trả lời được từ code, từ `compiled policy invariants`, hay từ quy
+  ước sẵn có thì đừng hỏi — đó là đẩy việc ngược về principal.
+
+## Ví dụ
+
+**Kiến trúc**
+
+> Kết quả kiểm chứng lưu ở đâu?
+> 1. Thêm mục vào `plan.md` *(đề nghị — plan là nguồn sự thật duy nhất, compiled policy invariants)*
+> 2. Tạo file `validation-answers.md` riêng
+> 3. Không lưu
+
+**Giả định**
+
+> Kế hoạch đang giả định không cần giới hạn tần suất. Đúng không?
+> 1. Đúng, bản đầu chưa cần
+> 2. Không, thêm mức cơ bản ngay *(đề nghị — thêm sau tốn hơn nhiều)*
+> 3. Hoãn sang phase 2
+
+## Mẫu nhật ký kiểm chứng
+
+```markdown
+## Nhật ký kiểm chứng
+
+### Lượt {N} — {YYYY-MM-DD}
+**Vì sao kiểm chứng:** {cái gì dẫn tới lượt này}
+**Số câu hỏi:** {n}
+
+#### Hỏi và đáp
+
+1. **[{Nhóm}]** {nguyên văn câu hỏi}
+   - Phương án: {A} | {B} | {C}
+   - **Principal chọn:** {đáp án}
+   - **Nguyên văn nếu principal trả lời khác:** {chép đúng chữ}
+   - **Vì sao quan trọng:** {quyết định này ảnh hưởng gì}
+
+#### Quyết định đã chốt
+- {quyết định}: {lựa chọn} — {vì sao}
+
+#### Việc phải làm
+- [ ] {thay đổi cụ thể}
+
+#### Ảnh hưởng tới phase
+- Phase {N}: {phải sửa gì, vì sao}
+```
+
+## Luật ghi
+
+- **Nguyên văn câu hỏi**, không tóm tắt.
+- **Đủ mọi phương án đã trình** — để sau này biết principal đã chọn giữa những gì.
+- **Chép đúng chữ** nếu principal trả lời ngoài các phương án. Diễn giải lại là bóp méo.
+- **Ghi vì sao** quyết định đó ảnh hưởng tới cách triển khai.
+- **Đánh số lượt** tăng dần.
+
+## Lan quyết định xuống phase
+
+| Loại thay đổi | Sửa vào mục nào của phase |
+|---|---|
+| yêu cầu | Việc phải làm |
+| kiến trúc | Kiến trúc / Việc phải làm |
+| phạm vi | Mục tiêu, và **Ngoài phạm vi** của `plan.md` |
+| rủi ro | Rủi ro |
+| chưa rõ thuộc đâu | thêm mục mới, đừng nhét bừa |
+
+Bước lan xuống phase là bước hay bị bỏ nhất và đắt nhất: người thực thi đọc **phase**, chứ
+không đọc `plan.md`. Ghi quyết định vào `plan.md` rồi quên sửa phase nghĩa là quyết định đó
+không tồn tại.

package/skills/alp-plan/references/validate-workflow.md

@@ -0,0 +1,83 @@
+# Phỏng vấn kiểm chứng kế hoạch
+
+Hỏi principal những câu hỏi then chốt để kiểm chứng giả định và chốt quyết định — **trước**
+khi bắt tay viết code.
+
+Khác với rà đối kháng: rà đối kháng tìm chỗ hỏng trong kế hoạch, phỏng vấn kiểm chứng tìm
+chỗ kế hoạch **đang đoán thay principal**.
+
+## 1. Đọc kế hoạch
+
+`plan.md` và toàn bộ `phase-*.md`. Tìm ba thứ:
+
+- **Điểm quyết định** — chỗ có nhiều hướng mà kế hoạch đã chọn một.
+- **Giả định** — thứ kế hoạch coi là đúng mà chưa ai xác nhận.
+- **Đánh đổi** — chỗ được cái này mất cái kia.
+
+## 2. Rút chủ đề hỏi
+
+`references/validate-question-framework.md`.
+
+## 3. Soạn câu hỏi
+
+Mỗi chủ đề → **một câu hỏi cụ thể, kèm 2–4 phương án**. Đánh dấu phương án bạn đề nghị và
+nói vì sao.
+
+**Chỉ hỏi điểm quyết định thật.** Câu hỏi mà bạn tự trả lời được từ code, từ `compiled policy invariants`,
+hoặc từ quy ước sẵn có thì **đừng hỏi** — đó là đẩy việc ngược về principal.
+
+Ba câu đủ thì hỏi ba. Kế hoạch đơn giản mà hỏi tám câu là làm phiền, không phải cẩn thận.
+
+## 4. Hỏi
+
+Hỏi thẳng trong phiên — không có `AskUserQuestion`, và cũng không cần.
+
+Gom câu hỏi liên quan lại một lượt thay vì hỏi lắt nhắt từng câu.
+
+## 5. Ghi lại
+
+Thêm mục `## Nhật ký kiểm chứng` vào `plan.md`:
+
+```markdown
+## Nhật ký kiểm chứng
+
+### Lượt 1 — YYYY-MM-DD
+
+| Câu hỏi | Principal chọn | Ảnh hưởng |
+|---|---|---|
+| <câu hỏi> | <đáp án> | <phase nào phải sửa> |
+```
+
+Ghi lại là bắt buộc, không phải tuỳ chọn: compiled policy invariants — markdown là source of truth. Câu
+trả lời chỉ nằm trong context phiên thì phiên sau mất sạch.
+
+## 6. Lan quyết định xuống phase
+
+Sửa các `phase-*.md` bị ảnh hưởng, kèm dấu:
+
+```markdown
+<!-- Sửa: kiểm chứng lượt N — <đổi gì> -->
+```
+
+Bước này hay bị bỏ, và bỏ thì hỏng nặng: `plan.md` ghi một đằng, phase ghi một nẻo, và
+người thực thi đọc phase chứ không đọc `plan.md`.
+
+## Đầu ra
+
+```
+Kiểm chứng: <đường dẫn kế hoạch>
+Đã hỏi: n câu
+Quyết định đã chốt: <tóm tắt>
+Phase đã sửa: <danh sách>
+Khuyến nghị: tiến hành | sửa lại kế hoạch
+```
+
+## Bước sau
+
+Báo principal đường dẫn kế hoạch và tóm tắt. **Dừng ở đó.**
+
+Kế hoạch được duyệt thì mới triển khai. alp-code không có bước bàn giao sang một vai
+"cook" nào cả.
+
+Sang phiên mới để triển khai thì nhớ: phiên mới **không thấy** gì của phiên này. Đường dẫn
+kế hoạch phải đưa đầy đủ, và `plan.md` phải tự đứng được một mình.

package/skills/alp-predict/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: alp-predict
+description: Năm persona chuyên môn phân tích độc lập một đề xuất thay đổi rồi tranh luận để ra phán quyết GO/THẬN TRỌNG/DỪNG. Kích hoạt khi cần phản biện trước một quyết định rủi ro cao, khi so sánh nhiều phương án kiến trúc, hoặc khi một migration khó đảo ngược.
+---
+
+# alp-predict — năm persona tranh luận
+
+Công cụ chính cho việc **phản biện độc lập trước một quyết định rủi ro cao**.
+
+Giá trị nằm ở chỗ ép năm góc nhìn nói **trước khi** biết nhau nghĩ gì. Để chúng ảnh hưởng
+nhau ngay từ đầu thì cả năm hội tụ về ý kiến của cái đầu tiên, và bài tập thành diễn.
+
+## Khi nào dùng
+
+- Kiến trúc có nhiều đánh đổi, hoặc migration khó đảo ngược.
+- Đã có phương án và cần người tìm cách bác nó.
+- Hai phương án cạnh tranh, cần so có cấu trúc chứ không so cảm tính.
+
+**Không dùng cho:** thay đổi nhỏ, việc đã chốt và chỉ còn triển khai, nâng phiên bản phụ
+thuộc không đổi API. Gọi năm persona cho một quyết định nhỏ là đốt ngân sách phiên và làm
+loãng giá trị của phán quyết DỪNG.
+
+## Năm persona
+
+| Persona | Soi gì | Câu hỏi lõi |
+|---|---|---|
+| **Kiến trúc** | thiết kế hệ, khả năng mở rộng, coupling | Có khớp kiến trúc hiện tại không? Sinh ra phụ thuộc mới nào? |
+| **Bảo mật** | bề mặt tấn công, bảo vệ dữ liệu, xác thực | Lạm dụng được chỗ nào? Dữ liệu hở ở đâu? Ranh giới quyền có bị phá? |
+| **Hiệu năng** | độ trễ, bộ nhớ, truy vấn, kích thước bundle | Trễ thêm bao nhiêu? Có N+1 không? Rò bộ nhớ? |
+| **Trải nghiệm** | UX, tiếp cận, trạng thái lỗi | Có trực giác không? Lỗi thì người dùng thấy gì? |
+| **Phản biện** | giả định ngầm, phương án đơn giản hơn | Không làm gì thì sao? Cách đơn giản nhất là gì? Giả định nào có thể sai? |
+
+## Quy trình
+
+1. **Đọc đề xuất** được đưa. Không rõ ranh giới thì hỏi lại — đoán sai phạm vi thì cả năm
+   persona phân tích nhầm thứ.
+2. **Đọc code liên quan** nếu có đường dẫn. `Grep` tìm vùng ảnh hưởng.
+3. **Từng persona phân tích độc lập.** Viết xong persona này mới sang persona kia; không
+   sửa lại persona trước cho khớp.
+4. **Gom điểm đồng thuận** — chỗ cả năm (hoặc 4+) cùng ý.
+5. **Gom điểm xung đột** — chỗ thật sự trái nhau, không phải khác cách diễn đạt.
+6. **Cân đánh đổi** từng xung đột: mối lo nào tác động lớn hơn, và nếu chọn sai thì đảo
+   ngược tốn bao nhiêu.
+7. **Ra phán quyết.**
+
+## Phán quyết
+
+| Mức | Nghĩa |
+|---|---|
+| **GO** | năm persona thống nhất, không rủi ro nghiêm trọng, làm được |
+| **THẬN TRỌNG** | có lo ngại nhưng xử lý được — đã chỉ ra cách giảm thiểu |
+| **DỪNG** | có vấn đề nghiêm trọng chưa giải quyết — cần thiết kế lại hoặc thêm thông tin |
+
+**Kích hoạt DỪNG** (chỉ cần một):
+
+- Bảo mật thấy vượt xác thực hoặc lộ dữ liệu mà không có cách giảm thiểu khả thi.
+- Kiến trúc thấy không tương thích nền tảng, phải làm lại phần lớn.
+- Hiệu năng thấy độ trễ hoặc bùng nổ truy vấn không chấp nhận được, không có đường vòng.
+- Phản biện lật được một giả định sai làm sụp cả cách tiếp cận.
+
+DỪNG là phán quyết **đắt**. Dùng nó cho thứ thật sự phải dừng, không dùng để tỏ ra cẩn thận.
+
+## Mẫu xuất
+
+```
+## Dự đoán: <tên đề xuất>
+
+## Phán quyết: GO | THẬN TRỌNG | DỪNG
+
+### Đồng thuận
+- <điểm cả năm cùng ý>
+
+### Xung đột và cách giải
+
+| Vấn đề | Kiến trúc | Bảo mật | Hiệu năng | Trải nghiệm | Phản biện | Kết luận |
+|---|---|---|---|---|---|---|
+| <chủ đề> | <ý> | <ý> | <ý> | <ý> | <ý> | <chọn gì, vì sao> |
+
+### Rủi ro
+
+| Rủi ro | Mức | Cách giảm thiểu | Chi phí nếu sai |
+|---|---|---|---|
+| <mô tả> | cao/vừa/thấp | <hành động cụ thể> | <đảo ngược tốn gì> |
+
+### Khuyến nghị
+1. <hành động — vì sao>
+
+### Chưa đủ thông tin để kết luận
+<phần nào cần được cung cấp thêm>
+```
+
+## Sau đó
+
+- Phán quyết đi về **bên giao việc**, không đi đâu khác.
+- Rủi ro cần bổ chi tiết thành edge case → đề xuất một lượt `alp-scenario` riêng.
+- Giả định sai bị lật ra → nói thẳng nó làm hỏng phần nào của kế hoạch, đừng gói trong
+  ngôn ngữ lịch sự. Người ta mở một lượt phản biện chính là để nghe điều đó.
+- Nháp và giả thuyết chưa kiểm chứng → kho riêng của bạn trong `memory/private/`.