# CASAN Plan-21 — Hybrid Global Install + `casan init`

> Ngày lập: 2026-07-23  
> Trạng thái: **IMPLEMENTED + HARDENED — global install + selectable IDE init + pinned global bootstrap + VS Code `@casan` + merge-safe/vendored migration (66/66 hybrid acceptance)**
> Liên quan: [Plan-20](CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md) (adapter/hook là base phổ quát), [CASAN_INSTALL_HYBRID.md](../casan/CASAN_INSTALL_HYBRID.md)

## 1. Mục tiêu

Cài CASAN như một tool bình thường (giống codegraph): cài **một lần** lên máy,
rồi trong dự án chỉ chạy `casan init`. Không còn copy toàn bộ harness vào từng
repo. Đây là câu trả lời cho "làm sao dựng 1 base chung nhất cho dự án muôn hình
vạn trạng": **harness = phần chung (agnostic), config per-project = phần biến
thể**, và entry phổ quát nhất là agentic bridge Plan-20 (chỉ cần Python + bash).

## 2. Kiến trúc

Tận dụng sẵn `casan-paths.sh` đã tách 3 root độc lập:

- `CASAN_HARNESS_ROOT` = **code** → cài global (`$CASAN_HOME/versions/<ver>`).
- `CASAN_STATE_ROOT` (`.specify/`) = **state runtime** → trong repo.
- `CASAN_DOMAIN_ROOT` = **dữ liệu dự án** → trong repo (optional).

Launcher global set `CASAN_HARNESS_ROOT`/`CASAN_DEVKIT_ROOT` về bản cài, và tìm
`CASAN_APP_ROOT` bằng cách đi lên từ CWD tới marker `.casan`/`.specify`. Nhờ vậy
harness global thao tác đúng trên state của dự án hiện tại.

## 3. Pin + Verify (giữ đảm bảo Plan-16 khi harness ở ngoài repo)

- Installer tính **hash toàn vẹn gate-code** (`scripts/bash`, `scripts/python`,
  `security`, `level5`, `adapters`, `schemas`) và ghi `.harness-hash`.
- `casan init` **pin** version + hash vào `.casan/version.lock`.
- `casan verify-harness` **tính lại live** từ file thật và so với pin → phát hiện
  drift/tamper (rc 3). Không tin hash cache.
- Làm mạnh sau: ký `.harness-hash` bằng khóa tổ chức (tái dùng hạ tầng ký Plan-16).

## 4. Deliverable đã ship

| Deliverable | File |
|---|---|
| Global installer (macOS/Linux) | `install.sh` |
| Global installer (Windows) | `install.ps1` |
| Integrity hash primitive | `packages/casan-harness/scripts/python/harness_hash.py` |
| `casan init` / `verify` | `packages/casan-devkit/casan-init.py` |
| CLI wiring | `bin/casan` (`init`, `verify-harness`) |
| Acceptance suite | `packages/casan-devkit/tests/hybrid-install-tests.sh` — **66/66 PASS** |
| Adoption doc | `docs/casan/CASAN_INSTALL_HYBRID.md` |

### Level selection (4 packaging levels) & safe adoption

- `install.sh --level core|devkit` (driven by `packaging/levels.json`); `platform`
  refused as a preview SERVICE, `enterprise` refused (future). Level recorded in
  `.casan-level`; launcher self-locates its own install (no cross-home talk).
- `casan init --level 1..4`: L1 = gate + Plan-20 hooks only; L2 = + CI workflow +
  domain-pack; L3 = L2 base + preview note; L4 = refused. `casan level show`/`set`.
- `casan init` trên TTY hiển thị menu chọn `claude`, `codex`,
  `vscode-copilot`; automation dùng repeatable/comma-separated `--client`.
- **Merge, not clobber:** `init` merges Plan-20 hooks into an existing
  `.claude/settings.json` / `.codex/hooks.json` idempotently, preserving the
  project's own hooks/agents/skills. Legacy CASAN-only TOML blocks are removed
  precisely; user TOML is preserved. Never re-indexes or rewrites the project shell.
- **Global-hook bootstrap:** hook chỉ gọi `.casan/casan-hook.py`; bootstrap tự
  load enforcement config, resolve harness global và verify live hash trước khi
  dispatch. Không còn đường dẫn sai `packages/casan-harness` trong consumer repo.
- **VS Code/Copilot:** build/install dependency-free VSIX đóng góp explicit
  `@casan` Chat Participant. Built-in Copilot không bị claim là global-intercept.
- **Source-hub guardrail:** `init` refuses to adopt a CASAN source hub into itself
  (would block the developing agent); `--force` overrides.
- **Vendored migration:** a consumer repo containing an older
  `packages/casan-harness` is distinguished from the product source hub,
  migrated without `--force`, and retains its project-owned agents, skills,
  prompts, workflows, scripts, evidence, and compatibility harness.

## 5. Definition of Done

- ✅ `install.sh` cài harness + launcher + integrity hash từ checkout cục bộ.
- ✅ `casan init` ghi CHỈ config per-project; **không** copy harness.
- ✅ `version.lock` pin đúng hash; `verify-harness` ok khi sạch, drift (rc 3) khi tamper.
- ✅ Bridge Plan-20 chạy qua harness global, state ghi vào `.specify` của dự án.
- ✅ Generated Claude/Codex commands được acceptance test thực thi end-to-end
  qua harness global; Codex template dùng current nested command-hook schema.
- ✅ `casan doctor` kiểm tra pin/bootstrap/client smoke/VS Code extension state.
- ✅ Claude Code 2.1.197 black-box: prompt injection bị UserPromptSubmit hook
  chặn, `duration_api_ms=0`, token/cost = 0.
- ✅ Project id mặc định theo tên thư mục, được sanitize.

## 6. Còn lại / bước tiếp

- **Remote bootstrap**: `install.sh`/`install.ps1` đã hỗ trợ `CASAN_DIST_URL`
  nhưng chưa có release tarball + URL Gitea công bố; cần publish artifact.
- **Windows thực**: `install.ps1` viết path-safe nhưng chưa chạy trên máy Windows
  thật (host dev không có `pwsh`).
- **Ký `.harness-hash`**: verify hiện theo nội dung; thêm chữ ký để chống thay cả
  hash lẫn code.
- **`casan init` domain pack**: hiện init tối giản (config + hook Plan-20); có thể
  thêm `--with-domain` để scaffold domain-pack khi dự án cần traceability đầy đủ.