alp-code 0.9.0

package/skills/alp-debug/scripts/find-polluter.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files
+TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
+TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0

package/skills/alp-debug/scripts/find-polluter.test.md

@@ -0,0 +1,102 @@
+# find-polluter.sh Test Documentation
+
+## Purpose
+Bisection script to find which test creates unwanted files or state pollution.
+
+## Manual Test Procedure
+
+### Setup Test Scenario
+```bash
+# Create test directory
+mkdir -p /tmp/polluter-test && cd /tmp/polluter-test
+
+# Create clean test
+cat > test1.test.js << 'EOF'
+console.log('Test 1: clean');
+EOF
+
+# Create polluter test
+cat > test2.test.js << 'EOF'
+const fs = require('fs');
+fs.mkdirSync('.git', { recursive: true });
+console.log('Test 2: creates pollution');
+EOF
+
+# Create another clean test
+cat > test3.test.js << 'EOF'
+console.log('Test 3: clean');
+EOF
+```
+
+### Run Script
+```bash
+# For projects with npm test
+/path/to/find-polluter.sh '.git' 'src/**/*.test.ts'
+
+# For node-only tests (modify script to use 'node' instead of 'npm test')
+./find-polluter.sh '.git' '*.test.js'
+```
+
+### Expected Output
+```
+🔍 Searching for test that creates: .git
+Test pattern: *.test.js
+
+Found 3 test files
+
+[1/3] Testing: ./test1.test.js
+[2/3] Testing: ./test2.test.js
+
+🎯 FOUND POLLUTER!
+   Test: ./test2.test.js
+   Created: .git
+```
+
+### Cleanup
+```bash
+rm -rf /tmp/polluter-test
+```
+
+## Test Results
+
+✅ Script logic verified (2025-11-11)
+- Correctly iterates through test files
+- Detects pollution creation
+- Reports the polluting test file
+- Exits early when polluter found
+
+## Usage Notes
+
+**Prerequisites:**
+- Test runner (npm test) must be configured in project
+- Test pattern must match actual test files
+- Pollution path must be accurate
+
+**Customization:**
+If your project doesn't use `npm test`, modify line 42:
+```bash
+# Replace
+npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+# With your test command
+node "$TEST_FILE" > /dev/null 2>&1 || true
+# Or
+jest "$TEST_FILE" > /dev/null 2>&1 || true
+```
+
+## Common Use Cases
+
+1. **Find test creating .git directory:**
+   ```bash
+   ./find-polluter.sh '.git' 'src/**/*.test.ts'
+   ```
+
+2. **Find test creating node_modules:**
+   ```bash
+   ./find-polluter.sh 'node_modules' 'test/**/*.spec.js'
+   ```
+
+3. **Find test creating specific file:**
+   ```bash
+   ./find-polluter.sh 'unwanted-file.txt' '**/*.test.js'
+   ```

package/skills/alp-plan/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: alp-plan
+description: Lập kế hoạch triển khai — thách thức phạm vi, thu thập bối cảnh, thiết kế giải pháp, chia phase, viết plan vào plans/. Kích hoạt khi principal giao một việc đủ lớn để cần chia bước, khi phải chốt kiến trúc trước lúc viết code, hoặc khi cần rà kế hoạch cũ trước khi mở kế hoạch mới.
+---
+
+# alp-plan — chốt kiến trúc trước khi gõ code
+
+Kế hoạch là hợp đồng bạn ký với principal — và là thứ người thực thi đọc để biết mình
+được giao gì.
+
+**Không viết code trong lúc lập kế hoạch.** Ra plan, principal duyệt, rồi mới làm.
+
+## Trước khi mở kế hoạch mới
+
+1. **Quét `plans/` tìm kế hoạch chưa xong.** Đọc frontmatter `status:` của từng `plan.md`.
+   Kế hoạch dở dang trùng phạm vi mà không ai biết là cách chắc chắn nhất để làm hai lần
+   cùng một việc theo hai hướng khác nhau.
+
+2. **Phát hiện quan hệ chặn.** So phạm vi: file đụng nhau, phụ thuộc chung, cùng vùng tính năng.
+
+   | Quan hệ | Ghi vào frontmatter |
+   |---|---|
+   | kế hoạch mới cần kết quả của kế hoạch cũ | mới: `blockedBy: [<dir cũ>]` |
+   | kế hoạch mới đổi thứ kế hoạch cũ đang dựa vào | cũ: `blockedBy: [<dir mới>]` · mới: `blocks: [<dir cũ>]` |
+   | phụ thuộc hai chiều | cả hai cùng ghi |
+
+   **Cập nhật cả hai file.** Ghi một chiều thì lần quét sau chỉ thấy một nửa quan hệ.
+
+3. **Không rõ thì hỏi.** Một câu hỏi ngắn rẻ hơn nhiều so với lập sai cả kế hoạch.
+
+## Bốn bước
+
+### 0. Thách thức phạm vi
+
+`references/scope-challenge.md`. **Bỏ qua nếu:** việc nhỏ rõ ràng (sửa một file, mô tả dưới
+20 từ).
+
+Câu hỏi đắt nhất hỏi ở đây: *không làm gì thì sao?* Và: *phần nào của yêu cầu này là thật
+sự cần, phần nào là mình tự thêm?* YAGNI áp dụng cho kế hoạch trước khi áp dụng cho code.
+
+### 1. Thu thập bối cảnh
+
+Bạn **không tự đi đọc hết**. Giao đúng vai — đó là lý do chúng tồn tại, và là cách giữ
+context của bạn sạch:
+
+| 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/cách làm bên ngoài | nghiên cứu nguồn ngoài |
+| đã từng quyết định gì về việc này | truy xuất trí nhớ |
+
+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>"`.
+
+Giao được nhiều vai **song song** thì dùng `--background` và theo dõi qua
+`alp delegation status|wait`. Runtime backend nằm sau API, không gọi trực tiếp.
+
+**Bỏ qua bước này nếu** principal đã đưa sẵn report, hoặc việc quá nhỏ.
+
+Chi tiết: `references/research-phase.md`, `references/codebase-understanding.md`.
+
+### 2. Thiết kế giải pháp
+
+`references/solution-design.md`.
+
+Rủi ro cao, khó đảo ngược, hoặc nhiều phương án cạnh tranh → **mở một lượt phản biện độc
+lập** (`alp-predict`) trước khi chốt. Phán quyết DỪNG nghĩa là thiết kế lại, không phải
+ghi chú thêm một dòng rủi ro rồi đi tiếp.
+
+### 3. Viết kế hoạch
+
+`references/plan-organization.md` và `references/output-standards.md`.
+
+## Định dạng — theo đúng repo
+
+```
+plans/{YYMMDD}-{HHMM}-{slug}/
+  plan.md              tổng quan, nguyên tắc, ngoài phạm vi
+  phase-0-<tên>.md     từng phase một file
+  phase-1-<tên>.md
+```
+
+Báo cáo: `plans/reports/{loại}-{YYMMDD}-{HHMM}-{slug}.md`.
+
+Frontmatter bắt buộc của `plan.md`:
+
+```yaml
+---
+status: draft | in-progress | completed | cancelled
+created: YYYY-MM-DD
+slug: <kebab>
+source: plans/reports/<report sinh ra kế hoạch này>.md
+blockedBy: []
+blocks: []
+---
+```
+
+`plan.md` phải có mục **Ngoài phạm vi**. Không có mục đó thì phạm vi sẽ tự phình trong lúc
+làm, và không ai chỉ ra được lúc nào nó phình.
+
+Mỗi file phase mở đầu bằng **Mục tiêu** một câu và **Phụ thuộc** (phase nào phải xong trước).
+
+## Chất lượng
+
+- Đủ chi tiết để một vai khác đọc và làm được mà không hỏi lại.
+- Nêu rõ **cách kiểm chứng** từng phase đã xong — không có tiêu chí thì phase không bao giờ
+  đóng được.
+- Nêu failure mode và cách giảm thiểu. Phase nào chưa nêu được thì chưa duyệt được.
+- Trong kế hoạch, ghi rõ phase nào **bắt buộc phải hỏi principal** trước khi chạy (thao tác
+  khó đảo ngược — HOUSE-RULES §1.2).
+- Tôn trọng YAGNI, KISS, DRY. Thẳng, phũ, ngắn.
+
+## Sau khi viết xong
+
+1. **Rà đối kháng** — `references/red-team-workflow.md`.
+2. **Phỏng vấn kiểm chứng** — `references/validate-workflow.md`.
+3. **Báo principal**: đường dẫn plan + tóm tắt + **câu hỏi còn mở ở cuối**.
+4. **Không tự bắt tay làm.** Principal duyệt rồi mới chạy.
+
+Kế hoạch xong hẳn → `references/archive-workflow.md`: đổi `status: completed`, ghi bài học
+vào `memory/private/<vai>/journal/YYYY-MM.md`.
+
+## Ranh giới
+
+- Không tạo plan hay report ngoài `plans/` của repo này.
+- Không có `Task` tool — mọi việc giao đi đều qua ALP Delegation API, là **execution riêng**,
+  không phải subagent. Execution chỉ thấy context ALP đã build: brief phải đủ.
+- Không có `AskUserQuestion`. Hỏi principal bằng cách hỏi thẳng trong phiên.

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

@@ -0,0 +1,77 @@
+# Quy trình đóng kế hoạch
+
+Chạy khi một kế hoạch đã xong, hoặc khi principal muốn dọn `plans/`.
+
+## 1. Đọc trạng thái thật
+
+```bash
+ls plans/
+```
+
+Với mỗi thư mục kế hoạch: đọc frontmatter `status:` của `plan.md`, và 20 dòng đầu của từng
+`phase-*.md`.
+
+**Đọc, đừng tin frontmatter.** `status: completed` mà còn phase chưa có tiêu chí hoàn thành
+nào được đánh dấu thì kế hoạch chưa xong — nó chỉ bị bỏ dở. Nói thẳng điều đó với principal.
+
+## 2. Ghi bài học
+
+Trước khi đóng, rút ra cái gì học được. Hai chỗ, đừng nhầm:
+
+| Loại | Ghi vào |
+|---|---|
+| bài học về **cách bạn làm việc** — quyết định nào sai, vì sao | `memory/private/<vai>/journal/YYYY-MM.md` |
+| fact về **project / principal / thế giới** | `memory/shared/` hoặc `memory/projects/` |
+
+Đây là HOUSE-RULES §2 và compiled policy invariants. Ghi fact chung vào journal riêng = nhân bản dữ liệu
+rồi để nó lệch — cấm.
+
+Bài học phải cụ thể. "Cần lập kế hoạch kỹ hơn" thì vô dụng. "Spike ACL ở P1.0 đổi kiến trúc
+P2 — lần sau spike trước khi chia phase" thì dùng được.
+
+## 3. Hỏi principal trước khi đóng
+
+Hỏi thẳng trong phiên. Ba câu:
+
+1. Đóng kế hoạch nào — cụ thể, hay tất cả kế hoạch đã `completed`?
+2. Chuyển sang `plans/archive/` hay xoá hẳn?
+3. Có commit luôn không?
+
+**Không tự quyết.** Xoá kế hoạch là hành động khó đảo ngược (HOUSE-RULES §1.2) — và
+`plans/` có commit vào git, nên xoá nhầm thì lấy lại được, nhưng đừng dựa vào đó.
+
+## 4. Đóng
+
+```bash
+mkdir -p plans/archive
+git mv plans/<thư-mục-kế-hoạch> plans/archive/
+```
+
+Dùng `git mv`, không dùng `mv` — giữ được lịch sử file.
+
+Principal chọn xoá hẳn thì `rm -rf plans/<thư-mục>` — **hỏi lại một lần nữa** trước khi chạy.
+
+Đổi `status:` trong `plan.md` thành `completed` hoặc `cancelled` **trước khi** chuyển đi.
+
+## 5. Dọn quan hệ chặn
+
+Kế hoạch bị đóng có thể đang nằm trong `blockedBy` của kế hoạch khác. Quét `plans/` còn lại,
+gỡ tham chiếu tới thư mục vừa đóng.
+
+Bỏ bước này thì lần quét sau sẽ thấy một kế hoạch bị chặn bởi thứ không còn tồn tại — và nó
+sẽ bị chặn mãi mãi.
+
+## 6. Báo cáo
+
+```
+Đã đóng: N kế hoạch · Đã xoá: N
+| Kế hoạch | Trạng thái | Tạo ngày | Ghi chú |
+|---|---|---|---|
+
+Journal: memory/private/<vai>/journal/YYYY-MM.md — <mục nào thêm mới>
+Quan hệ chặn đã gỡ: <kế hoạch nào>
+Commit: <hash hoặc "chưa — chờ principal">
+
+Câu hỏi còn mở:
+- …
+```

package/skills/alp-plan/references/codebase-understanding.md

@@ -0,0 +1,55 @@
+# Pha hiểu codebase
+
+**Bỏ qua khi:** đã có báo cáo truy xuất code đủ dùng.
+
+## Đọc luật trước, đọc code sau
+
+Đọc code trước khi biết luật là cách viết ra một kế hoạch đúng kỹ thuật nhưng sai quy ước.
+Với alp-code, thứ tự bắt buộc:
+
+| # | File | Cho biết |
+|---|---|---|
+| 1 | `compiled policy invariants` | sáu nguyên tắc bất biến, ai sửa được gì. **Chỉ principal sửa** |
+| 2 | `src/agents/shared/house-rules.ts` | luật cứng mọi vai, thứ tự ưu tiên khi xung đột |
+| 3 | `src/agents/<vai>.ts` | quy trình của chính bạn |
+| 4 | `README.md` | cây thư mục, bảng script |
+| 5 | `docs/` | tài liệu chuyên đề (delegation, ACL…) |
+
+Với repo **bên ngoài** (trong `workspaces.read`): đọc `README.md`, `repository instructions`/`repository instructions`,
+rồi `docs/` nếu có. Không có tài liệu thì nói rõ trong plan là kế hoạch dựng trên việc đọc
+code, không phải trên quy ước đã ghi.
+
+## Tìm code
+
+Giao cho vai chuyên truy xuất code (`scripts/run-role.sh <vai>`) — vai đó có `rg`, `Glob`,
+`Grep`, và `gkg` cho phân tích ảnh hưởng. Xem `research-phase.md` để biết cách viết brief.
+
+Tự tìm khi câu hỏi nhỏ và bạn đã biết đại khái file nào. Giao đi tốn một phiên; tự
+`rg` một lần tốn vài giây.
+
+## Nhận quy ước
+
+Trước khi thiết kế, trả lời được ba câu:
+
+1. **Chỗ này đã có mẫu chưa?** Có module tương tự thì theo nó, đừng phát minh cái thứ hai.
+   `README.md` của alp-code ghi rõ: `scripts/lib/` là "MỘT nguồn cho mỗi loại config".
+2. **Lỗi được xử lý kiểu gì?** Ném, trả về, hay fail đóng? alp-code chọn **fail đóng** —
+   hỏng thì hỏng to và thấy ngay, không hỏng im lặng.
+3. **Cái gì là sinh ra, cái gì là nguồn?** Sửa nhầm file sinh ra thì mất trong lần compile
+   kế tiếp. Trong alp-code: `compiled AgentDefinition` là nguồn; `~/.alp/executions/**` và
+   `$CODEX_HOME/<role>.config.toml` là sản phẩm.
+
+## Lập kế hoạch tích hợp
+
+- Tính năng mới nối vào kiến trúc hiện có ở đâu — đặt tên file, tên hàm cụ thể.
+- Đổi cái này thì vỡ những đâu. Không chắc → giao đi một lượt phân tích ảnh hưởng bằng `gkg`.
+- Tương thích ngược: có ai đang phụ thuộc hành vi cũ không.
+- Có phải sinh lại artifact không (`npm run build`), và ai chạy lệnh đó.
+
+## Ghi lại
+
+Phần hiểu được đi vào **plan**, không nằm lại trong context của phiên. Phiên sau không nhớ
+gì cả — compiled policy invariants: markdown là source of truth.
+
+Thấy nợ kỹ thuật hoặc chỗ không nhất quán → ghi vào mục **Ngoài phạm vi** của plan.
+**Không tự sửa** (HOUSE-RULES §1.6).

package/skills/alp-plan/references/output-standards.md

@@ -0,0 +1,96 @@
+# Chuẩn đầu ra
+
+## Frontmatter của `plan.md`
+
+Sáu trường, không hơn. Repo này đã dùng đúng bộ này — xem
+`plans/260821-0930-multi-agent-identity-memory/plan.md`.
+
+```yaml
+---
+status: draft | in-progress | completed | cancelled
+created: YYYY-MM-DD
+slug: <kebab>
+source: plans/reports/<report>.md
+blockedBy: []
+blocks: []
+---
+```
+
+| Trường | Điền thế nào |
+|---|---|
+| `status` | kế hoạch mới luôn là `draft` cho tới khi principal duyệt |
+| `created` | ngày hôm nay, `YYYY-MM-DD` |
+| `slug` | trùng phần slug của tên thư mục |
+| `source` | report sinh ra kế hoạch này. Không có thì bỏ trường |
+| `blockedBy` / `blocks` | phát hiện lúc quét trước khi tạo — `[]` nếu không có |
+
+**Không thêm trường.** `priority`, `effort`, `tags`, `branch`, `issue` là của bản gốc
+alp-plugin — chúng chỉ có nghĩa khi có dashboard đọc chúng. alp-code không có, nên thêm vào
+là dữ liệu không ai cập nhật rồi trôi lệch.
+
+## Chia phase
+
+- Mỗi phase **chạy được độc lập** sau khi phase phụ thuộc xong. Phase phải mở ba file mới
+  chạy nổi thì đó là hai phase.
+- Xếp theo **phụ thuộc và rủi ro**, không theo mức dễ. Phần rủi ro cao đi trước — biết sớm
+  rẻ hơn biết muộn.
+- Phase nào có spike quyết kiến trúc thì đặt trước, và ghi rõ: kết quả spike có thể đổi
+  phase sau.
+- Mỗi phase phải có **lệnh chạy được** làm tiêu chí hoàn thành.
+
+## File đụng tới
+
+Liệt kê kèm:
+
+- Đường dẫn **từ gốc repo** (`scripts/lib/loadout.cjs`), không phải đường dẫn tương đối
+  theo chỗ đang đứng.
+- Hành động: sửa / tạo / xoá.
+- Một câu đổi gì.
+- Phụ thuộc vào thay đổi nào khác.
+
+Hai loại file **không bao giờ đưa vào danh sách sửa**:
+
+| Loại | Vì sao |
+|---|---|
+| `~/.alp/executions/**`, `$CODEX_HOME/*.config.toml` | sản phẩm của `npm run build`. Sửa tay là mất ở lần compile sau |
+| `compiled policy invariants`, `src/agents/shared/**`, `src/agents/registry.ts` | chỉ principal sửa (compiled policy invariants) |
+
+Kế hoạch cần đổi chúng thì ghi vào mục **Cần principal duyệt**, đừng ghi vào danh sách việc.
+
+## Văn phong
+
+Hy sinh ngữ pháp cho cô đọng. Gạch đầu dòng và bảng. Câu ngắn. Bỏ từ thừa.
+
+Viết cho một vai khác đọc và **làm được mà không hỏi lại**. Chỗ nào phải hỏi lại thì chỗ đó
+chưa viết xong.
+
+Trong plan, nói **vì sao chọn cách này** ở chỗ quyết định không hiển nhiên. Sáu tháng sau,
+`git log` cho biết đã làm gì; chỉ plan mới cho biết vì sao.
+
+## Câu hỏi còn mở
+
+**Luôn có mục này ở cuối `plan.md`**, kể cả khi rỗng (ghi "không").
+
+Đưa vào đây: chỗ cần principal làm rõ, quyết định kỹ thuật cần người quyết, ẩn số ảnh
+hưởng cách triển khai, đánh đổi cần quyết định nghiệp vụ.
+
+Hỏi thẳng trong phiên — không có `AskUserQuestion`, và cũng không cần. Có câu trả lời thì
+sửa lại plan và phase.
+
+## Chất lượng
+
+- **Đủ sâu:** nêu edge case và failure mode. Phase chưa nêu được failure mode thì chưa
+  duyệt được.
+- **Bền:** ghi lý do quyết định. Tránh over-engineering — YAGNI áp dụng cho kế hoạch trước
+  khi áp dụng cho code.
+- **Có căn cứ:** không chắc thì giao đi một lượt tra cứu, đừng đoán rồi viết như thật.
+- **Bảo mật và hiệu năng:** nêu ngay ở phase liên quan, không dồn vào một phase "review"
+  cuối.
+- **Khớp repo:** đối chiếu với mẫu đang có. Kế hoạch đúng kỹ thuật nhưng lệch quy ước thì
+  vẫn phải làm lại.
+
+## Không làm
+
+- **Không viết code trong lúc lập kế hoạch.** Ra plan, principal duyệt, rồi mới làm.
+- Không tạo plan hay report ngoài `plans/` của repo này.
+- Trả về **đường dẫn plan + tóm tắt**, không dán cả nội dung plan vào câu trả lời.

package/skills/alp-plan/references/plan-organization.md

@@ -0,0 +1,129 @@
+# Tổ chức file kế hoạch
+
+## Đường dẫn
+
+```
+plans/{YYMMDD}-{HHMM}-{slug}/
+  plan.md
+  phase-0-<tên>.md
+  phase-1-<tên>.md
+  ...
+```
+
+Báo cáo: `plans/reports/{loại}-{YYMMDD}-{HHMM}-{slug}.md`
+(`loại` = `brainstorm`, `research`, `review`, `skills`… — tên vai hoặc loại báo cáo).
+
+`{YYMMDD}-{HHMM}` lấy lúc **bắt đầu** kế hoạch, không đổi về sau. Slug là kebab, mô tả
+được, không đánh số.
+
+Ví dụ thật trong repo: `plans/260821-0930-multi-agent-identity-memory/`.
+
+**Không có hook nào inject đường dẫn.** Tự tính từ ngày giờ hiện tại.
+
+## `plan.md`
+
+Frontmatter bắt buộc:
+
+```yaml
+---
+status: draft | in-progress | completed | cancelled
+created: YYYY-MM-DD
+slug: <kebab>
+source: plans/reports/<report sinh ra kế hoạch này>.md
+blockedBy: []
+blocks: []
+---
+```
+
+Thân, theo đúng thứ tự này:
+
+```markdown
+# <Tiêu đề>
+
+## Tổng quan
+
+<2–5 câu: xây cái gì, cho ai, thay thế cái gì.>
+
+Nguồn sự thật: [<report>](../reports/<file>.md).
+
+**Ngoài phạm vi:** <liệt kê thẳng. Cái gì để lại cho sau, cái gì cố tình không làm.>
+
+## Nguyên tắc bất biến
+
+1. **<Nguyên tắc>.** <Vì sao. Vi phạm thì hỏng thế nào.>
+
+## Phase
+
+| Phase | Tên | Trạng thái |
+|---|---|---|
+| 0 | [Dựng khung](./phase-0-scaffold.md) | chưa làm |
+| 1 | [ACL](./phase-1-loadout-acl.md) | chưa làm |
+```
+
+Giữ `plan.md` **dưới 80 dòng**. Nó là cửa vào, không phải nơi chứa chi tiết.
+
+Hai mục hay bị bỏ và đều đắt khi bỏ:
+
+- **Ngoài phạm vi** — không có thì phạm vi tự phình trong lúc làm, và không ai chỉ ra được
+  lúc nào nó bắt đầu phình.
+- **Nguyên tắc bất biến** — cái neo để phase sau không mâu thuẫn phase trước.
+
+Text của link phải là **tên người đọc được**, không phải tên file:
+`[Dựng khung](./phase-0-scaffold.md)`, không phải `[phase-0-scaffold.md](...)`.
+
+## File phase
+
+Mở đầu bắt buộc:
+
+```markdown
+# P<n> — <tên>
+
+**Mục tiêu:** <một câu. Xong phase này thì cái gì đúng mà trước đó chưa đúng.>
+**Phụ thuộc:** <P trước đó, hoặc "không">
+
+---
+```
+
+Rồi các mục theo nhu cầu — **chỉ viết mục nào có nội dung thật**:
+
+| Mục | Khi nào cần |
+|---|---|
+| Bối cảnh | dẫn report, file, tài liệu liên quan |
+| Việc phải làm | các bước đánh số, cụ thể tới tên file và tên hàm |
+| File đụng tới | sửa gì, tạo gì, xoá gì |
+| **Tiêu chí hoàn thành** | **luôn luôn** — lệnh chạy được để chứng minh phase xong |
+| Rủi ro | failure mode + cách giảm thiểu |
+| Cần principal duyệt | thao tác khó đảo ngược trong phase này |
+
+**Không có tiêu chí hoàn thành thì phase không bao giờ đóng được.** Tiêu chí phải là thứ
+chạy được: `node scripts/doctor.cjs` sạch, `test-x.cjs` xanh — không phải "hoạt động tốt".
+
+Phase có spike (thử nghiệm để quyết kiến trúc) thì ghi thẳng: **không viết code phần sau
+trước khi spike xong**, vì kết quả spike có thể đổi cả phase kế tiếp.
+
+## Quan hệ giữa các kế hoạch
+
+Ghi vào frontmatter `blockedBy`/`blocks`, dùng tên thư mục kế hoạch.
+
+**Cập nhật cả hai file.** Ghi một chiều thì lần quét sau chỉ thấy một nửa.
+
+Có quan hệ chặn thì thêm bảng vào `plan.md`:
+
+```markdown
+## Phụ thuộc kế hoạch khác
+
+| Quan hệ | Kế hoạch | Trạng thái |
+|---|---|---|
+| Chặn | [<tên>](../<dir>/plan.md) | in-progress |
+```
+
+## Không có trong alp-code
+
+Bản gốc của skill này giả định vài thứ repo này không có — bỏ qua nếu gặp trong tài liệu cũ:
+
+| Không có | Thay bằng |
+|---|---|
+| `ck plan create` CLI | viết file trực tiếp bằng `Write` |
+| task hydration (`TaskCreate`) | không có hệ task; `plan.md` là nguồn sự thật duy nhất |
+| `set-active-plan.cjs` | không có khái niệm "kế hoạch đang hoạt động" |
+| hook inject `## Naming` / `## Plan Context` | tự tính đường dẫn |