alp-code 0.9.0

package/scripts/run-role.cjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// Deprecated compatibility wrapper. Identity-aware raw runtime launch is no longer
+// supported; accepted legacy flags are translated into `alp delegate` arguments.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSyncCommand } = require("./lib/delegation/command-runner.cjs");
+const repoRoot = path.resolve(__dirname, "..");
+const entry = path.join(repoRoot, "dist", "src", "cli", "alp.js");
+if (!fs.existsSync(entry)) {
+  const built = spawnSyncCommand("npm", ["run", "build"], { cwd: repoRoot, stdio: "inherit" });
+  if (built.error || built.status !== 0) process.exit(built.status || 2);
+}
+const input = process.argv.slice(2);
+const role = input.shift();
+if (!role) {
+  console.error("ERROR     run-role requires a role");
+  process.exit(2);
+}
+if (input.includes("--dry-run") || input.includes("--anchor")) {
+  console.error("ERROR     identity-aware raw-runtime shortcuts are unsupported; use `alp delegate`");
+  process.exit(2);
+}
+const output = ["delegate", role];
+for (let index = 0; index < input.length; index += 1) {
+  const value = input[index];
+  if (value === "--kind") {
+    console.error("ERROR     `--kind` chọn runtime, mà runtime giờ là hệ quả của nấc; dùng `alp mode set <nấc>` hoặc ALP_MODE");
+    process.exit(2);
+  }
+  else if (value === "--pane") output.push("--background");
+  else if (value === "--exec") continue;
+  else if (value === "--release") {
+    output.splice(0, output.length, "delegation", "cleanup", input[++index]);
+    break;
+  } else output.push(value);
+}
+process.env.ALP_REPO_ROOT = repoRoot;
+require(entry).main(output).then(
+  (code) => { process.exitCode = code; },
+  (error) => { console.error(`ERROR     ${error && error.message ? error.message : String(error)}`); process.exitCode = 2; },
+);

package/scripts/run-role.ps1

@@ -0,0 +1,4 @@
+$ErrorActionPreference = "Stop"
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+& node (Join-Path $ScriptDir "run-role.cjs") @args
+exit $LASTEXITCODE

package/scripts/run-role.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/run-role.cjs" "$@"

package/scripts/sync-project-index.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+#
+# sync-project-index.sh — kiểm soát Project Layer bằng `modified`.
+#
+# Quét frontmatter của mọi L1 card (memory/projects/<slug>/PROJECT.md), so sánh với L0
+# (memory/projects/INDEX.md) và với mtime của filesystem, rồi báo ba tín hiệu:
+#
+#   DRIFT   mtime > updated       → file bị sửa mà chưa đóng dấu `updated`
+#   STALE   ACTIVE, quá N ngày    → khai đang chạy nhưng không ai đụng tới
+#   ORPHAN  L1 ⟷ L0 lệch nhau     → card không có dòng index, hoặc ngược lại
+#
+# Dùng:
+#   sync-project-index.sh            # chỉ báo cáo (mặc định, không ghi gì)
+#   sync-project-index.sh --write    # sinh lại bảng L0 từ frontmatter L1
+#   STALE_DAYS=30 sync-project-index.sh
+#
+# Exit: 0 mọi thứ khớp · 1 có tín hiệu cần xử lý · 2 lỗi cấu hình
+#
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PROJECTS_DIR="$ROOT/memory/projects"
+INDEX_FILE="$PROJECTS_DIR/INDEX.md"
+STALE_DAYS="${STALE_DAYS:-14}"
+WRITE=0
+
+[[ "${1:-}" == "--write" ]] && WRITE=1
+[[ -f "$INDEX_FILE" ]] || { echo "Không thấy $INDEX_FILE" >&2; exit 2; }
+
+TODAY_EPOCH=$(date +%s)
+
+# Đọc một khoá từ YAML frontmatter (khối --- đầu tiên của file).
+read_fm() {
+  awk -v key="$2" '
+    /^---[[:space:]]*$/ { if (seen) exit; seen = 1; next }
+    seen && $0 ~ "^" key ":" {
+      sub("^" key ":[[:space:]]*", "")
+      gsub(/^["'"'"']|["'"'"']$/, "")
+      sub(/[[:space:]]+$/, "")
+      print
+      exit
+    }
+  ' "$1"
+}
+
+# YYYY-MM-DD → epoch. BSD date (macOS).
+date_to_epoch() { date -j -f "%Y-%m-%d" "$1" "+%s" 2>/dev/null || echo 0; }
+
+issues=0
+active_rows=""
+done_rows=""
+all_slugs=()
+
+shopt -s nullglob
+for card in "$PROJECTS_DIR"/*/PROJECT.md; do
+  dir="$(dirname "$card")"
+  dirname_slug="$(basename "$dir")"
+  [[ "$dirname_slug" == _* ]] && continue   # bỏ qua _template
+
+  slug="$(read_fm "$card" slug)"
+  status="$(read_fm "$card" status)"
+  priority="$(read_fm "$card" priority)"
+  summary="$(read_fm "$card" summary)"
+  updated="$(read_fm "$card" updated)"
+
+  # --- frontmatter thiếu hoặc sai ---
+  for field in slug status priority summary updated; do
+    if [[ -z "${!field}" ]]; then
+      echo "MISSING  $dirname_slug — thiếu \`$field:\` trong frontmatter"
+      issues=$((issues + 1))
+    fi
+  done
+  [[ -z "$slug" || -z "$updated" ]] && continue
+
+  if [[ "$slug" != "$dirname_slug" ]]; then
+    echo "MISMATCH $dirname_slug — slug frontmatter là '$slug', không khớp tên thư mục"
+    issues=$((issues + 1))
+  fi
+
+  # --- DRIFT: file bị chạm sau lần đóng dấu cuối ---
+  mtime_date="$(date -r "$card" "+%Y-%m-%d")"
+  updated_epoch="$(date_to_epoch "$updated")"
+  mtime_epoch="$(date_to_epoch "$mtime_date")"
+  if (( mtime_epoch > updated_epoch )); then
+    echo "DRIFT    $slug — sửa $mtime_date nhưng updated: $updated → đọc lại rồi đóng dấu"
+    issues=$((issues + 1))
+  fi
+
+  # --- STALE: khai ACTIVE mà lâu không đụng ---
+  if [[ "$status" == "ACTIVE" ]]; then
+    age_days=$(( (TODAY_EPOCH - updated_epoch) / 86400 ))
+    if (( age_days > STALE_DAYS )); then
+      echo "STALE    $slug — ACTIVE nhưng $age_days ngày không cập nhật (ngưỡng $STALE_DAYS)"
+      issues=$((issues + 1))
+    fi
+  fi
+
+  all_slugs+=("$slug")
+  if [[ "$status" == "DONE" ]]; then
+    done_rows+="| $slug | $priority | $summary | $updated |"$'\n'
+  else
+    active_rows+="$priority	$slug	| $slug | $priority | $status | $summary | $updated |"$'\n'
+  fi
+done
+shopt -u nullglob
+
+# --- sinh lại bảng L0 (làm trước, để ORPHAN kiểm tra trên bản mới nhất) ---
+if (( WRITE )); then
+  # sắp xếp cố định: priority rồi slug — để L0 ổn định byte giữa các lần chạy
+  active_tbl="$(mktemp)"; done_tbl="$(mktemp)"
+  trap 'rm -f "$active_tbl" "$done_tbl"' EXIT
+
+  {
+    echo "| Slug | P | Trạng thái | Tóm tắt | Cập nhật |"
+    echo "|---|---|---|---|---|"
+    if [[ -n "$active_rows" ]]; then
+      printf '%s' "$active_rows" | sort -t'	' -k1,1 -k2,2 | cut -f3-
+    else
+      echo "| _(chưa có)_ | | | | |"
+    fi
+  } > "$active_tbl"
+
+  if [[ -n "$done_rows" ]]; then
+    { echo "| Slug | P | Tóm tắt | Đóng ngày |"
+      echo "|---|---|---|---|"
+      printf '%s' "$done_rows" | sort
+    } > "$done_tbl"
+  else
+    echo "_(chưa có)_" > "$done_tbl"
+  fi
+
+  tmp="$(mktemp)"
+  awk -v active_f="$active_tbl" -v done_f="$done_tbl" '
+    function emit(f,   line) { while ((getline line < f) > 0) print line; close(f) }
+    /<!-- BEGIN:INDEX -->/ { print; emit(active_f); skip = 1; next }
+    /<!-- END:INDEX -->/   { skip = 0 }
+    /<!-- BEGIN:DONE -->/  { print; emit(done_f);   skip = 1; next }
+    /<!-- END:DONE -->/    { skip = 0 }
+    !skip
+  ' "$INDEX_FILE" > "$tmp"
+  mv "$tmp" "$INDEX_FILE"
+  echo "WROTE    INDEX.md — bảng L0 đã sinh lại từ frontmatter L1"
+fi
+
+# --- ORPHAN: card ⟷ dòng index, hai chiều ---
+for slug in ${all_slugs+"${all_slugs[@]}"}; do
+  if ! grep -q "^| $slug |" "$INDEX_FILE"; then
+    echo "ORPHAN   $slug — có PROJECT.md nhưng chưa có dòng trong INDEX.md (chạy --write)"
+    issues=$((issues + 1))
+  fi
+done
+
+while IFS= read -r indexed_slug; do
+  [[ -z "$indexed_slug" ]] && continue
+  if [[ ! -f "$PROJECTS_DIR/$indexed_slug/PROJECT.md" ]]; then
+    echo "ORPHAN   $indexed_slug — có dòng trong INDEX.md nhưng không có PROJECT.md"
+    issues=$((issues + 1))
+  fi
+done < <(awk -F'|' '/^\| [a-z0-9][a-z0-9-]* \|/ { gsub(/^[[:space:]]+|[[:space:]]+$/, "", $2); print $2 }' "$INDEX_FILE")
+
+if (( issues == 0 )); then
+  echo "OK       Project Layer khớp — không có DRIFT / STALE / ORPHAN"
+  exit 0
+fi
+echo "---"
+echo "$issues tín hiệu cần xử lý."
+exit 1

package/skills/agent-memory/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: agent-memory
+description: Luật ghi trí nhớ dùng chung cho mọi vai trong repo alp-code — khi nào ghi, ghi vào đâu, định dạng gì. Kích hoạt khi biết được fact mới về principal/project/thế giới, khi kết phiên, khi phân vân giữa shared/ và private/, hoặc khi cần tạo file trong memory/.
+---
+
+# agent-memory — ghi cái gì, vào đâu
+
+Trí nhớ là **thói quen**, không phải tính năng. Agent mất hết giữa các phiên trừ những gì
+được ghi lại. Nhưng ghi bừa còn tệ hơn không ghi: fact sai, fact trùng, fact lệch nhau
+giữa các vai đều tốn tiền hơn là quên.
+
+Quyền ghi của bạn nằm trong immutable execution policy → `memory.write`. Bảng dưới nói
+*nên* ghi vào đâu; compiled policy nói *được* ghi vào đâu. Không có quyền → **báo cho vai
+có quyền**, đừng ghi chỗ khác cho tiện.
+
+## Bảng định tuyến
+
+| Tình huống | Đích | Ai thấy |
+|---|---|---|
+| Sở thích / ràng buộc lặp lại của principal | `memory/shared/people/principal.md` | mọi vai |
+| Quyết định chung, không thuộc project nào | `memory/shared/decisions/YYMMDD-slug.md` | mọi vai |
+| Người / tổ chức | `memory/shared/people/<ten>.md` | mọi vai |
+| Link / dashboard / ticket / tài liệu ngoài | `memory/shared/reference/<slug>.md` | mọi vai |
+| Bối cảnh một project (mục tiêu, việc kế, cạm bẫy) | `memory/projects/<slug>/PROJECT.md` (L1) | mọi vai |
+| Quyết định của một project | `memory/projects/<slug>/decisions/YYMMDD-slug.md` (L2) | mọi vai |
+| Diễn biến một phiên | `memory/projects/<slug>/log/YYYY-MM.md` (L2) | mọi vai |
+| Tài liệu tra cứu cho một project | `memory/projects/<slug>/refs/<slug>.md` (L2) | mọi vai |
+| Nháp, giả thuyết **chưa kiểm chứng** | `memory/private/<role>/` | chỉ bạn |
+| Bài học về **chính agent này** | `memory/private/<role>/journal/YYYY-MM.md` | chỉ bạn |
+
+Giao thức Project Layer 3 tầng: `memory/projects/PROTOCOL.md`.
+
+## Bảy luật cứng
+
+1. **Fact về principal / project / thế giới → LUÔN `shared/` hoặc `projects/`.
+   KHÔNG BAO GIỜ `private/`.**
+   `private/` chỉ chứa nháp và self-log. Vi phạm = fact bị nhân bản giữa các vai rồi
+   lệch nhau, và không vai nào biết bản nào đúng. Đây là lỗi tốn kém nhất của hệ này.
+
+   *Kiểm nhanh:* "vai khác mà biết điều này thì có làm việc tốt hơn không?" → có = `shared/`.
+
+2. **Một fact = một file.** Đừng dồn. Ngày luôn tuyệt đối (`2026-08-21`), không "tuần sau".
+   Trùng thì gộp, sai thì **xoá** — trí nhớ sai nguy hiểm hơn không có trí nhớ.
+
+3. **Không ghi thứ repo đã ghi** — cấu trúc code, lịch sử git, compiled agent definitions.
+   Nếu `grep` ra được trong 5 giây thì đừng chép vào `memory/`.
+
+4. **File mới trong `memory/shared/` → thêm một dòng vào `memory/INDEX.md`.**
+   Định dạng: `- [Tiêu đề](shared/<thư-mục>/<file>.md) — móc câu một dòng`.
+   File không có dòng index = file không tồn tại với các phiên sau.
+
+5. **Sửa L1 (`PROJECT.md`) → đóng dấu `updated:` ngay.** Quên là sinh `DRIFT`, doctor sẽ kêu.
+
+6. **Không sửa tay bảng trong `projects/INDEX.md`.** Sửa frontmatter L1 rồi chạy
+   `scripts/sync-project-index.sh --write`.
+
+7. **Journal:** một file mỗi tháng, mỗi entry ≤5 dòng, >200 dòng thì nén lại.
+   Journal **không** nằm trong boot set — nó là chỗ nghĩ, không phải chỗ tra.
+
+## Frontmatter chuẩn
+
+```yaml
+---
+id: <slug ổn định, kebab-case>
+type: decision | person | reference | log | project
+layer: L1 | L2 | L3
+visibility: private | team
+owner: <role>
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: []
+source: <link | phiên>
+---
+```
+
+Thân file:
+
+```markdown
+# <Tiêu đề>
+
+<Một fact chính. Cụ thể, kiểm chứng được.>
+
+**Vì sao quan trọng:** <một dòng>
+**Áp dụng thế nào:** <một dòng>
+
+Liên quan: [[slug-khac]]
+```
+
+`[[slug]]` trỏ tới file chưa tồn tại là **bình thường** — đó là ghi chú cho việc cần viết
+sau, không phải lỗi.
+
+## Khi nào ghi
+
+**Ghi ngay** khi: principal nói ra một ràng buộc sẽ còn đúng tuần sau · một quyết định
+kiến trúc được chốt · phát hiện một hành vi hệ thống mà lần sau sẽ lại phải tra · một
+project đổi trạng thái.
+
+**Đừng ghi** khi: chỉ đúng trong phiên này · repo/git đã ghi · bạn chưa kiểm chứng
+(→ `private/` nếu vẫn muốn giữ) · trùng file đã có (→ sửa file đó).
+
+## Kết phiên
+
+1. Diễn biến → `memory/projects/<slug>/log/YYYY-MM.md`
+2. L1 `PROJECT.md` cập nhật + đóng dấu `updated:`
+3. Fact mới theo bảng trên; file mới trong `shared/` → thêm dòng vào `memory/INDEX.md`
+4. `scripts/sync-project-index.sh --write`
+
+Hook `Stop` nhắc nếu quên. Nó chỉ **nhắc** — không ghi thay bạn. Trích fact là việc ngữ
+nghĩa, hook không gọi LLM.

package/skills/alp-debug/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: alp-debug
+description: Điều tra sự cố có hệ thống — truy nguyên nhân gốc trước khi bàn cách sửa, phân tích log và CI/CD, chẩn đoán hiệu năng, kiểm chứng bằng bằng chứng. Kích hoạt khi bế tắc với một bug, test fail, hành vi lạ, pipeline hỏng, hoặc hệ chậm bất thường.
+---
+
+# alp-debug — điều tra trước, kết luận sau
+
+Dùng khi **đã có giả thuyết và bằng chứng mà vẫn bế tắc** — nên đừng bắt đầu lại từ đầu,
+hãy hỏi đã thử những gì rồi.
+
+## Luật cứng
+
+**KHÔNG KẾT LUẬN KHI CHƯA TRUY RA NGUYÊN NHÂN GỐC.**
+
+Đoán rồi sửa là cách tạo bug mới trong lúc giấu bug cũ. Và nếu loadout không cấp `Edit` thì luật
+này còn dễ giữ hơn: bạn **không sửa được gì**, chỉ giao nguyên nhân gốc cho người sửa.
+
+Hệ quả: sản phẩm của bạn là **chuỗi bằng chứng**, không phải bản vá. Một chuỗi bằng chứng
+tốt phải để người đọc tự đi lại được và tới cùng kết luận.
+
+## Chọn kỹ thuật
+
+```
+Bug trong code      → systematic-debugging.md      (4 pha, không nhảy pha)
+  sâu trong stack     → root-cause-tracing.md      (lần ngược tới chỗ phát sinh)
+  đã ra nguyên nhân   → defense-in-depth.md        (khuyến nghị chốt chặn từng lớp)
+  sắp kết luận        → verification.md            (bằng chứng mới, không dùng lại cũ)
+
+Sự cố mức hệ       → investigation-methodology.md  (5 bước)
+  CI/CD hỏng          → log-and-ci-analysis.md     (`gh` CLI)
+  chậm bất thường     → performance-diagnostics.md
+  cần viết báo cáo    → reporting-standards.md
+```
+
+| # | Kỹ thuật | Đọc khi |
+|---|---|---|
+| 1 | **Gỡ lỗi có hệ thống** | mọi bug cần điều tra — 4 pha: truy nguyên nhân → phân tích mẫu → thử giả thuyết → kết luận. Xong pha này mới sang pha kia |
+| 2 | **Lần ngược nguyên nhân** | lỗi nổ sâu trong call stack, chưa rõ dữ liệu hỏng sinh ra từ đâu. Có `scripts/find-polluter.sh` để bisect test bị nhiễm |
+| 3 | **Phòng thủ nhiều lớp** | đã ra nguyên nhân, cần chỉ ra nên chốt ở những lớp nào: chặn ở cửa vào → nghiệp vụ → guard môi trường → chỗ đặt log |
+| 4 | **Kiểm chứng** | sắp nói "đã tìm ra" hoặc "đã hết" |
+| 5 | **Phương pháp điều tra** | sự cố nhiều thành phần: đánh giá ban đầu → thu thập dữ liệu → phân tích → xác định gốc → phương án |
+| 6 | **Phân tích log và CI/CD** | pipeline hỏng, lỗi phía server, sự cố deploy |
+| 7 | **Chẩn đoán hiệu năng** | truy vấn chậm, độ trễ cao, cạn tài nguyên |
+| 8 | **Chuẩn báo cáo** | cần xuất báo cáo chẩn đoán có cấu trúc |
+
+## Công cụ có sẵn
+
+- **Database:** `psql` cho PostgreSQL.
+- **CI/CD:** `gh` CLI cho log GitHub Actions.
+- **Bế tắc thật sự:** skill `problem-solving` — đổi kiểu nghĩ, không nghĩ chăm hơn.
+
+Cần thứ bạn không lấy được (tìm code diện rộng, tra tài liệu ngoài) → **nói rõ cần gì và
+báo lại**. Loadout không cho giao việc thì đừng tự đi tìm đường vòng.
+
+## Cờ đỏ — dừng lại nếu bắt gặp mình đang nghĩ
+
+- "sửa tạm đã, điều tra sau"
+- "cứ thử đổi X xem sao"
+- "chắc là do X, sửa chỗ đó"
+- "chắc hết rồi" · "nhìn có vẻ ổn"
+- "test xanh rồi, xong"
+
+Tất cả đều nghĩa là: quay lại quy trình. Và còn một cờ đỏ nữa — **"để tôi sửa luôn"**:
+nếu loadout không cấp `Edit` thì viết đề xuất ra, đừng tìm đường vòng qua `Bash`
+(HOUSE-RULES §1.9).
+
+## Bàn giao
+
+Báo cáo gồm đúng bốn phần:
+
+```
+## Điều tra: <triệu chứng>
+
+### Nguyên nhân gốc
+<một câu. Chưa ra thì ghi "chưa xác định được" — không thay bằng nguyên nhân gần nhất>
+
+### Chuỗi bằng chứng
+1. <quan sát> — `path:line` hoặc output lệnh
+2. <suy ra> — vì sao bước 1 dẫn tới đây
+...
+
+### Đã loại trừ
+<giả thuyết nào đã thử và bị bác, bằng gì — để người đọc không đi lại đường cũ>
+
+### Đề xuất sửa
+<sửa ở đâu, vì sao ở đó chứ không phải chỗ triệu chứng nổ ra>
+```
+
+Nháp và giả thuyết chưa kiểm chứng → kho riêng của bạn trong `memory/private/`. Chỉ kết
+luận đã có bằng chứng mới đi vào báo cáo.

package/skills/alp-debug/references/defense-in-depth.md

@@ -0,0 +1,118 @@
+# Phòng thủ nhiều lớp
+
+Chốt chặn ở **mọi tầng** dữ liệu đi qua, để bug trở thành không thể xảy ra.
+
+Nếu loadout không cấp `Edit` thì bạn không tự thêm được chốt. File này dùng để **viết
+khuyến nghị**: chỉ ra nên chặn ở đâu, mỗi chỗ chặn cái gì, và vì sao một chỗ là không đủ.
+
+## Nguyên lý
+
+Sửa một bug do dữ liệu sai, thêm một chỗ kiểm là thấy đủ. Nhưng một chỗ kiểm bị vượt qua
+bởi: đường code khác, refactor sau này, hoặc mock trong test.
+
+```
+Một chỗ kiểm    → "đã sửa bug"
+Nhiều tầng chốt → "bug không thể xảy ra"
+```
+
+Mỗi tầng bắt được loại khác nhau — đó là lý do cần nhiều tầng, không phải vì thừa.
+
+## Bốn tầng
+
+### Tầng 1 — chặn ở cửa vào
+
+Từ chối input sai rõ ràng, ngay ở ranh giới API.
+
+```js
+function createProject(name, workingDirectory) {
+  if (!workingDirectory || workingDirectory.trim() === '')
+    throw new Error('workingDirectory không được rỗng');
+  if (!existsSync(workingDirectory))
+    throw new Error(`workingDirectory không tồn tại: ${workingDirectory}`);
+  if (!statSync(workingDirectory).isDirectory())
+    throw new Error(`workingDirectory không phải thư mục: ${workingDirectory}`);
+}
+```
+
+### Tầng 2 — chặn ở nghiệp vụ
+
+Dữ liệu có hợp lý **với thao tác này** không.
+
+```js
+function initializeWorkspace(projectDir, sessionId) {
+  if (!projectDir) throw new Error('initializeWorkspace cần projectDir');
+}
+```
+
+### Tầng 3 — guard môi trường
+
+Chặn thao tác nguy hiểm trong ngữ cảnh cụ thể.
+
+```js
+async function gitInit(directory) {
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmp = normalize(resolve(tmpdir()));
+    if (!normalized.startsWith(tmp))
+      throw new Error(`Từ chối git init ngoài thư mục tạm khi chạy test: ${directory}`);
+  }
+}
+```
+
+### Tầng 4 — chỗ đặt log
+
+Bắt bối cảnh để lần sau còn điều tra được.
+
+```js
+logger.debug('sắp git init', { directory, cwd: process.cwd(), stack: new Error().stack });
+```
+
+## Cách áp dụng
+
+1. **Lần dòng dữ liệu** — giá trị sai sinh ra ở đâu, được dùng ở đâu.
+2. **Liệt kê mọi trạm** dữ liệu đi qua.
+3. **Đề xuất chốt ở từng tầng** — cửa vào, nghiệp vụ, môi trường, log.
+4. **Đề xuất cách kiểm từng tầng** — thử vượt tầng 1, xác nhận tầng 2 bắt được.
+
+Bước 4 hay bị bỏ. Chốt chưa từng được kiểm là chốt chưa biết có hoạt động không.
+
+## Ví dụ thật
+
+**Bug:** `projectDir` rỗng làm `git init` chạy trong thư mục source.
+
+**Dòng dữ liệu:** test setup → chuỗi rỗng → `Project.create(name, '')` →
+`WorkspaceManager.createWorkspace('')` → `git init` chạy ở `process.cwd()`.
+
+| Tầng | Chốt |
+|---|---|
+| 1 | `Project.create()` kiểm không rỗng / tồn tại / ghi được |
+| 2 | `WorkspaceManager` từ chối `projectDir` rỗng |
+| 3 | `WorktreeManager` từ chối `git init` ngoài thư mục tạm khi chạy test |
+| 4 | log stack trace trước `git init` |
+
+**Kết quả:** 1847 test pass, bug không tái hiện được nữa.
+
+**Cả bốn tầng đều cần.** Trong lúc kiểm, mỗi tầng bắt được thứ tầng khác bỏ lọt: đường code
+khác vượt qua tầng 1 · mock vượt qua tầng 2 · ca biên trên nền tảng khác cần tầng 3 · log
+tầng 4 lộ ra chỗ dùng sai về mặt cấu trúc.
+
+## Với alp-code
+
+Repo này chọn **fail đóng** làm mặc định — hỏng thì hỏng to và thấy ngay. Vài chỗ đã theo
+đúng mẫu bốn tầng, dùng làm ví dụ khi viết khuyến nghị:
+
+| Tầng | Trong alp-code |
+|---|---|
+| 1 | `L.validate()` — loadout sai thì `npm run build` ném lỗi, không sinh settings hỏng |
+| 2 | `denyRules()` — deny của mọi vai anh em, enumerate từng cái |
+| 3 | `hooks/acl-guard.cjs` — chặn lúc chạy, kể cả khi settings hỏng |
+| 4 | `doctor.cjs` — tín hiệu `ACL-DRIFT`, `SKILL-DRIFT` khi hai bên lệch nhau |
+
+compiled policy invariants nói thẳng giới hạn: `acl-guard` là **guardrail, không phải sandbox**. Nhiều tầng
+chặn nhầm lẫn và vượt quyền tình cờ — không chặn được kẻ cố tình lách. Khuyến nghị phòng
+thủ nhiều lớp thì đừng hứa nhiều hơn mức nó làm được.
+
+## Chốt
+
+Đừng dừng ở một chỗ kiểm. Và khi viết khuyến nghị, nói rõ **mỗi tầng bắt được gì
+mà tầng khác bỏ lọt** — không có phần đó thì nó chỉ giống như bảo đi thêm việc.

package/skills/alp-debug/references/investigation-methodology.md

@@ -0,0 +1,106 @@
+# Phương pháp điều tra mức hệ
+
+Năm bước cho sự cố nhiều thành phần — khác với gỡ một bug trong code, ở đây bạn phải dựng
+lại **chuyện gì đã xảy ra** trước khi bàn tới sửa gì.
+
+## Khi nào dùng
+
+- Server trả 500 hoặc phản hồi lạ.
+- Hành vi hệ đổi mà không thấy code đổi.
+- Sự cố trải qua nhiều dịch vụ / database / hạ tầng.
+- Cần biết "đã xảy ra chuyện gì" trước khi bàn cách sửa.
+
+## Bước 1 — Đánh giá ban đầu
+
+Nắm phạm vi và mức ảnh hưởng **trước khi** lao vào chi tiết.
+
+1. **Gom triệu chứng** — thông báo lỗi, endpoint bị ảnh hưởng, mô tả của principal.
+2. **Xác định thành phần liên quan** — dịch vụ nào, database nào, hàng đợi nào.
+3. **Khoanh mốc thời gian** — bắt đầu từ khi nào? Trùng với deploy hay thay đổi nào?
+4. **Đánh giá mức nghiêm trọng** — ảnh hưởng ai, dữ liệu có rủi ro không.
+5. **Xem gì vừa đổi.**
+
+```bash
+gh run list --limit 10
+git log --oneline -20 --since="2 days ago"
+git diff HEAD~5 -- '*.env*' '*.config*' '*.yml' '*.yaml' '*.json'
+```
+
+Bước 5 giải quyết một tỷ lệ lớn sự cố ngay tại chỗ. Làm trước khi làm gì phức tạp hơn.
+
+## Bước 2 — Thu thập dữ liệu
+
+Gom bằng chứng **có hệ thống**, trước khi phân tích. Vừa gom vừa suy diễn dẫn tới việc chỉ
+gom thứ khớp với giả thuyết đầu tiên.
+
+1. **Log ứng dụng / server** — lọc theo mốc thời gian và thành phần.
+2. **Log CI/CD** — xem `log-and-ci-analysis.md`.
+3. **Trạng thái database** — truy vấn bảng liên quan, kiểm migration gần đây.
+4. **Số đo hệ thống** — CPU, bộ nhớ, đĩa, mạng.
+5. **Phụ thuộc bên ngoài** — API bên thứ ba, DNS, CDN.
+
+```bash
+gh run list --workflow=<workflow> --limit 5
+gh run view <run-id> --log-failed
+gh run view <run-id> --log > /tmp/ci-logs.txt
+```
+
+**Cần hiểu codebase lạ:** báo lại để nhờ một lượt truy xuất code hoặc tra tài liệu ngoài.
+Loadout không cho giao việc thì đừng tự đi làm phần đó.
+
+## Bước 3 — Phân tích
+
+Đối chiếu chéo giữa các nguồn.
+
+1. **Dựng lại mốc thời gian** — xếp sự kiện theo thứ tự, gộp mọi nguồn log.
+2. **Nhận mẫu** — lỗi lặp lại, mẫu theo thời điểm, nhóm người dùng bị ảnh hưởng.
+3. **Lần đường thực thi** — request đi qua những thành phần nào.
+4. **Phân tích database** — hiệu năng truy vấn, quan hệ bảng, toàn vẹn dữ liệu.
+5. **Vẽ phụ thuộc** — thành phần nào phụ thuộc thành phần đang hỏng.
+
+Bốn câu hỏi then chốt:
+
+- Có trùng với một lần deploy hay một khung giờ cụ thể không?
+- Xảy ra lúc có lúc không, hay luôn luôn?
+- Ảnh hưởng mọi người dùng hay một nhóm?
+- Dịch vụ phía trước / phía sau có lỗi liên quan không?
+
+## Bước 4 — Xác định nguyên nhân gốc
+
+Loại trừ có hệ thống, bằng bằng chứng.
+
+1. **Liệt kê giả thuyết**, xếp theo độ mạnh của bằng chứng.
+2. **Thử từng cái** — thí nghiệm nhỏ nhất đủ để xác nhận hoặc loại bỏ.
+3. **Xác nhận bằng bằng chứng** — log, số đo, bước tái hiện.
+4. **Xét yếu tố môi trường** — race condition, giới hạn tài nguyên, config trôi lệch.
+5. **Ghi lại cả chuỗi** — từ chỗ kích hoạt tới triệu chứng.
+
+**Tránh:** sửa theo giả thuyết đầu tiên mà chưa thử các giả thuyết khác. Nhiều nguyên nhân
+đều hợp lý thì phải loại trừ, không phải chọn cái tiện nhất.
+
+Ghi rõ giả thuyết nào **đã bị bác và bằng gì** — không có phần đó, người đọc sẽ đi lại đúng con
+đường bạn vừa đi.
+
+## Bước 5 — Đề xuất phương án
+
+Bạn đề xuất, người khác thực hiện. Tách rõ ba loại:
+
+| Loại | Nội dung |
+|---|---|
+| **Ngay** | thay đổi nhỏ nhất để khôi phục — hotfix, rollback, đổi config |
+| **Gốc** | xử lý dứt điểm nguyên nhân gốc |
+| **Phòng ngừa** | giám sát, cảnh báo, chốt chặn để lần sau phát hiện sớm |
+
+Thứ tự ưu tiên: **ảnh hưởng × mức khẩn**. Khôi phục trước, sửa gốc sau, phòng ngừa sau nữa.
+
+Đánh dấu rõ phương án nào là thao tác **khó đảo ngược** (rollback production, migration,
+xoá dữ liệu) — phải xin principal duyệt trước khi chạy (HOUSE-RULES §1.2).
+
+## Khi thu hẹp được về code cụ thể
+
+| Chuyển sang | Khi |
+|---|---|
+| `systematic-debugging.md` | đã khoanh về một vùng code |
+| `root-cause-tracing.md` | lỗi nổ sâu trong call stack |
+| `defense-in-depth.md` | đã ra nguyên nhân, cần khuyến nghị chốt chặn |
+| `verification.md` | trước khi phát biểu kết luận |