feat(install): Plan-21 hybrid global install + casan init (pin+verify)

Adopt CASAN like a normal tool (codegraph-style): install the harness ONCE
per machine, then `casan init` per project writes CONFIG ONLY — the harness
is no longer copied into every repo.

- install.sh / install.ps1: global bootstrap (curl|sh / irm|iex or local
  source). Installs harness to $CASAN_HOME/versions/<ver>, writes a `casan`
  launcher that resolves the shared harness + the current project's .specify,
  and records a gate-code integrity hash. CASAN_NO_PATH_LINK for tests.
- harness_hash.py: deterministic content hash over gate code (scripts/bash,
  scripts/python, security, level5) — the pin+verify anchor.
- casan-init.py: `casan init` writes .casan/{config,version.lock,agentic.env},
  .specify/ marker, and the Plan-20 client hooks — no harness copy. `verify`
  recomputes the harness hash LIVE and compares to the project pin (drift/
  tamper -> rc 3), preserving the Plan-16 trusted-gates guarantee off-repo.
- bin/casan: new `init` and `verify-harness` commands.
- hybrid-install-tests.sh: 21/21 (install, config-only init, no-copy, pin,
  verify ok, tamper drift, bridge runs against project state via global harness).
- docs: CASAN_INSTALL_HYBRID.md + Plan-21.

The path model (casan-paths.sh) already separated harness/state/domain roots,
so this is installer + init, not a core rewrite. Remote dist tarball, real
Windows run, and signed .harness-hash are the documented next steps.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/casan/CASAN_INSTALL_HYBRID.md

@@ -0,0 +1,101 @@
+# Cài CASAN kiểu tool (global install + `casan init`) — Plan-21
+
+Mô hình **hybrid**: cài harness **một lần** vào máy (`$CASAN_HOME`), sau đó mỗi
+dự án chỉ chạy `casan init` để ghi **config riêng của dự án** — harness KHÔNG bị
+copy vào từng repo. Giống trải nghiệm codegraph.
+
+## 1. Cài đặt (một lần cho mỗi máy)
+
+```bash
+# macOS / Linux
+curl -fsSL https://<your-gitea>/admin/casan5/raw/branch/main/install.sh | sh
+
+# Windows (PowerShell)
+irm https://<your-gitea>/admin/casan5/raw/branch/main/install.ps1 | iex
+```
+
+Hoặc từ một checkout CASAN có sẵn:
+
+```bash
+sh install.sh                 # macOS/Linux
+pwsh .\install.ps1            # Windows
+```
+
+Installer sẽ:
+
+- Copy harness vào `$CASAN_HOME/versions/<version>` (mặc định `~/.casan`,
+  Windows: `%LOCALAPPDATA%\casan`) và trỏ `current` vào version đó.
+- Ghi **hash toàn vẹn** của gate-code (`.harness-hash`) — mỏ neo cho pin+verify.
+- Tạo launcher `casan` và đưa lên PATH (`~/.local/bin` hoặc `$CASAN_HOME/bin`).
+
+> Windows cần **Git for Windows (Git Bash)** để *chạy* harness (xem
+> [CASAN_AGENTIC_CLIENTS_WINDOWS.md](CASAN_AGENTIC_CLIENTS_WINDOWS.md)) — không
+> cần WSL2. Cả hai OS cần `python3`.
+
+Biến môi trường hữu ích: `CASAN_HOME` (đổi nơi cài), `CASAN_SRC` (cài từ checkout
+cục bộ), `CASAN_DIST_URL` (tải tarball), `CASAN_NO_PATH_LINK=1` (không tự thêm PATH).
+
+## 2. Adopt vào một dự án bất kỳ
+
+```bash
+cd <dự-án-của-bạn>
+casan init                       # project id lấy theo tên thư mục
+# hoặc:
+casan init --project my-app --client all --mode observe
+```
+
+`casan init` chỉ ghi **config per-project** (không copy harness):
+
+| File | Vai trò |
+|---|---|
+| `.casan/config.json` | project id, enforcement/integration mode, clients |
+| `.casan/version.lock` | **pin** harness version + hash gate-code |
+| `.casan/agentic.env` | feature flags bridge Plan-20 |
+| `.specify/` | thư mục state runtime (logs/trace/admission) |
+| `.claude/settings.json` | hook Claude Code (Plan-20) |
+| `.codex/hooks.json`, `config.toml` | hook Codex (Plan-20) |
+
+Tham số: `--client claude|codex|all` (mặc định `all`), `--mode observe|enforce`
+(mặc định `observe`), `--integration-mode project_hook|managed_hook|casan_owned`,
+`--target <dir>` (mặc định thư mục hiện tại).
+
+Sau `init`, developer gõ prompt bình thường trong client — trace H1→H7 + H6 theo
+Plan-20. Repo chỉ có mấy file config nhỏ; nâng cấp harness làm ở `$CASAN_HOME`.
+
+## 3. Pin + Verify (giữ đảm bảo bảo mật khi harness ở ngoài repo)
+
+Vì harness không nằm trong repo, dự án **pin** version + hash gate-code lúc
+`init`. Kiểm tra bất cứ lúc nào:
+
+```bash
+casan verify-harness
+```
+
+- Khớp → `status: ok` (rc 0).
+- Harness global bị đổi/tamper so với pin → `HARNESS_INTEGRITY_DRIFT` (rc 3).
+
+`verify-harness` **luôn tính lại hash từ file thật** (không tin hash cache), nên
+sửa lén một gate script sẽ bị phát hiện. Nên chạy `verify-harness` trong CI trước
+khi tin bất kỳ trace nào là certified.
+
+> Bước làm mạnh tiếp theo (chưa bật mặc định): ký `.harness-hash` bằng khóa tổ
+> chức để verify cả *chữ ký* chứ không chỉ nội dung — dùng hạ tầng ký của Plan-16.
+
+## 4. So sánh với mô hình vendored cũ
+
+| | Vendored (`devkit/install.sh`) | Hybrid (`casan init`) |
+|---|---|---|
+| Repo | Nặng (copy cả harness) | Nhẹ (chỉ config) |
+| Nâng cấp | Mỗi repo tự drift | 1 chỗ (`$CASAN_HOME`) |
+| Bảo mật | Gate commit + ký trong repo | Gate global + **pin+verify** trong repo |
+| CI/offline | Tự chứa | Cần cài harness trên runner (hoặc verify pin) |
+
+Cả hai vẫn dùng chung lõi harness + `casan-paths.sh` (tách `CASAN_HARNESS_ROOT`
+= code, `CASAN_STATE_ROOT` = state trong repo, `CASAN_DOMAIN_ROOT` = dữ liệu dự
+án). Chọn mô hình theo nhu cầu triển khai.
+
+## 5. Kiểm thử
+
+```bash
+bash packages/casan-devkit/tests/hybrid-install-tests.sh
+```