CASAN/docs/casan/CASAN_INSTALL_HYBRID.md

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)

# 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:

sh install.sh                 # macOS/Linux
pwsh .\install.ps1            # Windows

Chọn level đóng gói để cài (theo packaging/levels.json):

sh install.sh --level core      # L1: harness + gates + CLI (casan run/gate/verify)
sh install.sh --level devkit    # L2 (mặc định): + adoption tooling (casan init, CI, domain-pack)
sh install.sh --level platform  # L3 preview: từ chối — là service, deploy riêng
sh install.sh --level enterprise# L4 future: từ chối (chưa ship)

Levels là cumulative (devkit ⊃ core). casan init là tính năng của L2 (devkit); cài --level core sẽ không có casan init (báo rõ ràng).

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.
• Ghi level đã cài vào .casan-level.
• Tạo launcher casan (tự định vị install của chính nó) 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) — 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ỳ

cd <dự-án-của-bạn>
casan init                       # interactive: chọn Claude, Codex, VS Code/Copilot
# hoặc chọn level áp dụng cho project:
casan init --level 1 --project my-app --client claude
casan init --level 2 --project my-app --client claude,codex
casan init --project my-app --client vscode-copilot --vscode-install yes
casan level show                        # xem level đã cài + level project
casan level set 2                       # đổi level project (không cần init lại)

Áp dụng cho dự án ĐÃ có vỏ (agents/skills/hook sẵn): an toàn.

• init KHÔNG index/parse code, KHÔNG sửa source, KHÔNG dựng lại vỏ — chỉ thêm config.
• Hook được MERGE idempotent vào .claude/settings.json / .codex/hooks.json hiện có (giữ nguyên hook/agents/skills/khóa khác của bạn), không ghi đè. Chạy init nhiều lần không nhân đôi hook.
• Guardrail: init từ chối khi target chính là một CASAN source hub (để không tự chặn agent đang phát triển CASAN); dùng --force nếu thực sự cần.
• Project cũ có vendored packages/casan-harness không bị xem là source hub: init tự migrate sang hybrid, giữ nguyên harness/CI/scripts cũ để tương thích và không yêu cầu --force.

--level 3 (platform) chỉ áp base L2 + nhắc rằng platform là service deploy riêng; --level 4 (enterprise) bị từ chối (chưa ship).

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
.casan/casan-hook.py	bootstrap stdlib: load config, resolve + verify harness global, dispatch adapter
.specify/	thư mục state runtime (logs/trace/admission)
.claude/settings.json	hook Claude Code (Plan-20)
.codex/hooks.json	hook Codex theo schema hiện hành; cần review/trust bằng /hooks
.vscode/extensions.json	recommendations cho IDE đã chọn

Tham số --client có thể lặp hoặc comma-separated: claude, codex, vscode-copilot, all, none. Khi chạy casan init trực tiếp trong terminal, CLI hiển thị menu chọn. Trong automation không có TTY, mặc định tương thích ngược là claude,codex.

--mode observe|enforce mặc định enforce; dùng observe chỉ cho pilot telemetry-only. --integration-mode nhận project_hook|managed_hook|casan_owned; --target <dir> mặc định là thư mục hiện tại.

Bootstrap .casan/casan-hook.py tự đọc config.json; developer không còn phải source .casan/agentic.env trước khi mở IDE. Mỗi invocation kiểm tra live hash của harness global so với version.lock trước khi chạy adapter.

Project đã có .claude, .github, agents, skills hoặc CASAN vendored

Chỉ cần commit/backup trạng thái hiện tại, cài CASAN global rồi chạy init tại project root, kể cả khi đường dẫn có khoảng trắng:

cd '/path/to/Basic Design (Screen&Report)_v2.7'
casan init --project basic-design-v27 --client claude,codex,vscode-copilot
casan doctor

Quy tắc migration:

• .claude/agents, .claude/skills, .claude/commands, .github/** và workflow hiện hữu không bị xóa hoặc ghi đè.
• CASAN chỉ merge handler của mình vào .claude/settings.json và .codex/hooks.json; cấu hình/hook không thuộc CASAN được giữ nguyên.
• Nếu có CASAN vendored cũ, packages/casan-harness, bin/casan-chat, CI và evidence cũ được giữ lại. Chỉ xóa chúng sau khi CI/scripts/domain smoke đã chuyển sang harness global.
• Block legacy nằm đúng giữa marker CASAN_PROMPT_ENFORCEMENT_START/END được nâng cấp tự động.
• Prose legacy nằm ngoài marker không bị sửa âm thầm; init và doctor liệt kê file cần review. Đặc biệt phải bỏ tuyên bố cũ rằng Claude/Codex direct chat luôn nằm ngoài CASAN, vì Plan-20 project hooks đã thay đổi hành vi đó.
• Codex vẫn cần /hooks trust; Copilot built-in vẫn cần explicit @casan.

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.

Capability theo client

Lựa chọn	Trải nghiệm	Bước trust/cài đặt bắt buộc
claude	Claude Code CLI và extension chính thức dùng project hooks	Mở trusted project; hook chạy tự động
codex	Codex CLI và IDE extension dùng .codex/hooks.json	Mở /hooks, review và trust đúng hook hash
vscode-copilot	GitHub Copilot Chat qua route explicit @casan	Cài VSIX do init tạo/cài; dùng @casan <prompt>

GitHub Copilot Chat mặc định không có public API để CASAN intercept mọi prompt. Chỉ route @casan là casan_owned; participant detection/built-in Copilot không được quảng bá là certified.

Kiểm tra sau init:

casan doctor
casan doctor --client claude
casan doctor --client codex
casan doctor --client vscode-copilot

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:

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 packages/casan-devkit/tests/hybrid-install-tests.sh