gitea-admin/CASAN
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add production Core runtime modes

Browse Source
This commit is contained in:
thanhnv
2026-07-24 12:16:11 +07:00
parent e359989a74
commit eb3525456f
13 changed files with 659 additions and 397 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/casan/CASAN_ADOPTION_WINDOWS.md
+89 -143
View File
@@ -1,204 +1,150 @@
# Áp dụng CASAN từ đầu trên Windows
# Áp dụng CASAN production trên Windows
Tài liệu này dành cho thành viên đã có một repository dự án nhưng repository đó **chưa có CASAN**. CASAN Core được clone riêng từ Gitea, sau đó DevKit cài runtime và policy vào repository dự án.
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.
Giá trị sau được installer thay theo dự án:
## 1. Yêu cầu
- Project ID: `__PROJECT_ID__`
- Project name: `__PROJECT_NAME__`
## 1. Phạm vi hỗ trợ
Luồng này áp dụng cho agent coding chạy tại project root:
- Claude Code;
- Codex;
- GitHub Copilot Coding Agent;
- GitHub Copilot hoặc agent plugin trong VS Code có hỗ trợ repository instructions.
CASAN CLI đầy đủ chạy trong WSL2. PowerShell chỉ đóng vai trò gọi wrapper WSL2.
## 2. Cài WSL2 và công cụ nền
Trong PowerShell Administrator, nếu máy chưa có WSL2:
```powershell
wsl --install -d Ubuntu
```
Khởi động lại Windows nếu được yêu cầu. Sau đó mở PowerShell thường và cài công cụ trong Ubuntu:
```powershell
wsl -d Ubuntu -- bash -lc 'sudo apt-get update && sudo apt-get install -y git python3 rsync'
wsl -d Ubuntu -- bash -lc 'git --version && python3 --version && rsync --version | head -1'
```
SSH key truy cập Gitea phải được cấu hình trong `~/.ssh` của WSL hoặc thông qua cơ chế quản lý key đã được tổ chức phê duyệt. Không đặt private key trong repository.
## 3. Khai báo đường dẫn
Thay hai đường dẫn Windows và URL Gitea theo môi trường thực tế:
```powershell
$TargetProjectWin = 'C:\Projects\my-existing-project'
$CasanSourceWin = 'C:\Projects\.casan-source\casan-core'
$CasanRepo = 'ssh://git@<gitea-host>:<port>/<owner>/<casan-repo>.git'
$TargetProjectWsl = (wsl -d Ubuntu -- wslpath -a $TargetProjectWin).Trim()
$CasanSourceWsl = (wsl -d Ubuntu -- wslpath -a $CasanSourceWin).Trim()
```
- 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:
```powershell
wsl -d Ubuntu -- bash -lc "test -d '$TargetProjectWsl' && printf 'TARGET_OK=%s\n' '$TargetProjectWsl'"
python --version
git --version
Get-Command bash
```
Nếu dự án là Git repository, commit hoặc lưu riêng thay đổi hiện có trước khi adoption:
## 2. Cài DevKit một lần trên máy
Từ checkout CASAN:
```powershell
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && git status --short --branch"
pwsh .\install.ps1 -Level devkit
```
Không dùng `git reset --hard` hoặc `git clean` để chuẩn bị cài đặt.
## 4. Clone CASAN Core từ Gitea
Clone lần đầu:
Mở terminal mới và kiểm tra:
```powershell
New-Item -ItemType Directory -Force -Path (Split-Path $CasanSourceWin -Parent) | Out-Null
wsl -d Ubuntu -- bash -lc "git clone '$CasanRepo' '$CasanSourceWsl'"
casan version
```
Nếu đã clone, chỉ cập nhật bằng fast-forward khi working tree CASAN sạch:
```powershell
wsl -d Ubuntu -- bash -lc "cd '$CasanSourceWsl' && git status --short --branch && git pull --ff-only origin main"
```
## 5. Cài CASAN vào repository dự án
```powershell
wsl -d Ubuntu -- bash -lc "cd '$CasanSourceWsl' && bash packages/casan-devkit/install.sh --target '$TargetProjectWsl' --project '__PROJECT_ID__' --domain '__PROJECT_NAME__'"
```
Installer tạo hoặc cập nhật:
- `packages/casan-harness/` — CASAN Core H1-H7;
- `bin/casan` — CLI;
- `bin/casan-chat` và `bin/casan-chat.ps1` — prompt entrypoint;
- `.casan/prompt-policy.json` — project binding;
- `apps/__PROJECT_ID__/domain/` — domain pack ban đầu;
- `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md` — agent enforcement block;
- `.gitea/workflows/casan-prompt-enforcement.yml` — kiểm tra contract trên CI;
- `docs/casan/` — hướng dẫn đã render cho dự án.
Installer giữ nội dung bên ngoài CASAN marker, tài liệu domain hiện hữu, project registry và workflow CI hiện hữu.
## 6. Thay domain scaffold bằng context thật
Hoàn thiện tối thiểu:
Runtime managed mặc định nằm dưới:
```text
apps/__PROJECT_ID__/domain/input/requirement.md
apps/__PROJECT_ID__/domain/input/architecture.md
apps/__PROJECT_ID__/domain/golden-runs/
apps/__PROJECT_ID__/domain/traceability-map.json
apps/__PROJECT_ID__/domain/corpus/
%LOCALAPPDATA%\casan\current
```
Không đưa source tree lớn, binary, log, build output, credential hoặc dữ liệu nhạy cảm vào context mặc định. Chỉ khai báo những context root cần thiết và có chủ đích.
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.
## 7. Xác minh installation contract
## 3. Adopt repository
```powershell
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && bin/casan prompt verify"
Set-Location 'C:\Projects\my-existing-project'
casan init --project my-existing-project --client claude,codex
casan doctor
casan verify-harness
casan level show
```
Kết quả bắt buộc:
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:
```powershell
casan init --runtime vendored --project my-existing-project --client claude,codex
```
Core production-only được đặt tại:
```text
CASAN_PROMPT_ENFORCEMENT_VALID project=__PROJECT_ID__ mode=enforced
.casan\runtime\casan-core\
bin\casan
packages\casan-harness\
VERSION
```
Nếu lệnh thất bại, dừng sử dụng agent và sửa đúng artifact được báo thiếu hoặc sai.
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.
## 8. Chạy gate ban đầu
Chạy lại `casan init` giữ runtime mode hiện tại. Chuyển mode phải explicit:
```powershell
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && CASAN_DOMAIN_ROOT='apps/__PROJECT_ID__/domain' bin/casan gate"
casan init --runtime managed
casan init --runtime vendored
```
Gate có thể fail khi domain pack chưa có requirement, golden run hoặc corpus thật. Không sửa report để đổi FAIL thành PASS; bổ sung đúng evidence còn thiếu.
## 5. Client integration
## 9. Gửi prompt qua CASAN
- 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.
Từ project root trong PowerShell:
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:
```powershell
Set-Location $TargetProjectWin
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1 "Review the current requirements and identify missing acceptance criteria."
casan verify-harness
casan gate
```
Chế độ tương tác:
Vendored mode có local CLI:
```powershell
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1
.\.casan\runtime\casan-core\bin\casan verify-harness
.\.casan\runtime\casan-core\bin\casan gate
```
Mỗi lượt thành công phải có `certified=true`, `trace_id` và dòng `CASAN_PROMPT_TRACE_CERTIFIED ... gates=7`.
Luôn chạy `verify-harness` trước gate để phát hiện runtime drift/tamper.
## 10. Xác minh một prompt
## 7. Uninstall
```powershell
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && bin/casan prompt trace '<trace-id>'"
casan uninstall
```
Kết quả hợp lệ:
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.
```text
CASAN_PROMPT_TRACE_CERTIFIED project=__PROJECT_ID__ trace_id=<trace-id> gates=7
```
## 11. Dùng với Claude Code, Codex và Copilot
Mở agent tại đúng `$TargetProjectWin`. Agent phải đọc instruction tương ứng:
- Codex: `AGENTS.md`;
- Claude Code: `CLAUDE.md`;
- GitHub Copilot: `.github/copilot-instructions.md`.
Nếu plugin không hỗ trợ repository instructions hoặc tính năng đó đang tắt, không được coi prompt là đã enforce. Prompt trực tiếp không có CASAN trace không được gắn nhãn certified.
Chi tiết role, codegen và approval nằm trong `docs/casan/CASAN_PROMPT_ENFORCEMENT.md`.
## 12. Commit adoption vào repository dự án
Sau khi review diff và chạy verify:
Xóa thêm runtime evidence:
```powershell
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && git status --short"
casan uninstall --purge
```
Commit các artifact CASAN cần được chia sẻ cho team. Không commit `.specify/` runtime log nếu policy repository yêu cầu giữ telemetry ngoài Git.
## 13. Nâng cấp CASAN
Chỉ gỡ extension dùng chung khi chắc chắn không project nào khác cần:
```powershell
wsl -d Ubuntu -- bash -lc "cd '$CasanSourceWsl' && git pull --ff-only origin main"
wsl -d Ubuntu -- bash -lc "cd '$CasanSourceWsl' && bash packages/casan-devkit/install.sh --target '$TargetProjectWsl' --project '__PROJECT_ID__' --domain '__PROJECT_NAME__'"
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && bin/casan prompt verify"
casan uninstall --remove-vscode-extension
```
## Checklist bàn giao
- [ ] WSL2 có Git, Python 3 và rsync.
- [ ] CASAN Core được clone riêng từ Gitea và đang ở `main` mới nhất.
- [ ] Installer hoàn tất cho project `__PROJECT_ID__`.
- [ ] Domain pack đã dùng context/evidence thật.
- [ ] `bin/casan prompt verify` đạt.
- [ ] Agent coding được mở tại project root và đọc repository instructions.
- [ ] Prompt mẫu trả `certified=true` và trace H1-H7 xác minh được.
- [ ] H6 telemetry có `project_id=__PROJECT_ID__`.
- [ ] Workflow `casan-prompt-enforcement.yml` được commit và chạy trên push/PR.
- [ ] `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.