CASAN/docs/plans/CASAN_PLAN_21_HYBRID_INSTALL.md

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 (adapter/hook là base phổ quát), 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 đủ.