CASAN/docs/casan/CASAN_ADOPTION_WINDOWS.md

Áp dụng CASAN production trên Windows

Tài liệu này dành cho repository hiện hữu chưa có CASAN. Windows dùng PowerShell để cài CLI và Git for Windows/Git Bash để chạy các gate Bash. WSL2 không bắt buộc.

1. Yêu cầu

• PowerShell 5.1+ hoặc PowerShell 7;
• Python 3 trên PATH;
• Git for Windows, bao gồm bash.exe;
• quyền đọc CASAN release/checkout đã được tổ chức phê duyệt.

Kiểm tra:

python --version
git --version
Get-Command bash

2. Cài DevKit một lần trên máy

Từ checkout CASAN:

pwsh .\install.ps1 -Level devkit

Mở terminal mới và kiểm tra:

casan version

Runtime managed mặc định nằm dưới:

%LOCALAPPDATA%\casan\current

Global package phải là DevKit vì lệnh adoption casan init nằm trong DevKit. Project vẫn mặc định áp dụng Level 1/Core.

3. Adopt repository

Set-Location 'C:\Projects\my-existing-project'
casan init --project my-existing-project --client claude,codex
casan doctor
casan verify-harness
casan level show

Output phải hiển thị rõ:

• project level: Core (1);
• runtime mode: Managed;
• đường dẫn Core thực tế;
• version và integrity hash đã pin.

Managed mode chỉ ghi config/lock/bootstrap và client hooks vào repository; Core được dùng từ global install.

4. Chế độ self-contained/air-gapped

Nếu khách hàng yêu cầu Core nằm trong repository:

casan init --runtime vendored --project my-existing-project --client claude,codex

Core production-only được đặt tại:

.casan\runtime\casan-core\
  bin\casan
  packages\casan-harness\
  VERSION

Folder này không chứa tests, legacy level5, internal CI runners hoặc Platform-only helpers. Project hook, global launcher và local CLI đều resolve runtime này theo .casan\version.lock. Nếu vendored Core bị thiếu hoặc sai hash, CASAN fail closed và không fallback âm thầm sang global Core.

Chạy lại casan init giữ runtime mode hiện tại. Chuyển mode phải explicit:

casan init --runtime managed
casan init --runtime vendored

5. Client integration

• Claude: CASAN merge hook vào .claude\settings.json.
• Codex: CASAN merge hook vào .codex\hooks.json; mở /hooks để review/trust.
• VS Code/Copilot: dùng --client vscode-copilot; route được chứng nhận là explicit @casan, không phải toàn bộ Copilot Chat.

CASAN không xóa hook, agent, skill, instruction hoặc workflow không thuộc CASAN.

6. CI

Managed mode: runner phải cài đúng CASAN release đã pin trước khi chạy:

casan verify-harness
casan gate

Vendored mode có local CLI:

.\.casan\runtime\casan-core\bin\casan verify-harness
.\.casan\runtime\casan-core\bin\casan gate

Luôn chạy verify-harness trước gate để phát hiện runtime drift/tamper.

7. Uninstall

casan uninstall

Lệnh xóa CASAN hooks/config, CASAN-owned Gitea workflow, scaffold chưa chỉnh sửa và toàn bộ vendored Core nếu có. Hook/workflow/file project được giữ lại.

Xóa thêm runtime evidence:

casan uninstall --purge

Chỉ gỡ extension dùng chung khi chắc chắn không project nào khác cần:

casan uninstall --remove-vscode-extension

Checklist bàn giao

• casan version chạy trong terminal mới.
• casan level show hiển thị đúng level, runtime mode và path.
• .casan\version.lock có version, runtime mode/path và hash.
• casan doctor đạt.
• casan verify-harness đạt.
• Codex hook đã được review/trust nếu chọn Codex.
• CI verify đúng runtime đã pin trước khi chạy gate.