feat: add production Core runtime modes
This commit is contained in:
thanhnv
@@ -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.
|
||||
|
||||
@@ -105,4 +105,4 @@ Plan-20 **không** quảng bá `project_hook` như một sandbox tuyệt đối.
|
||||
exit gate.
|
||||
- Trace sinh trong observe mode luôn `observed_only`, **không** retroactively
|
||||
certified.
|
||||
- Rollback chỉ tắt adapter; `bin/casan-chat` và core H1→H7 hiện tại vẫn hoạt động.
|
||||
- Rollback chỉ tắt adapter; Core H1→H7 đã pin theo project vẫn hoạt động.
|
||||
|
||||
@@ -1,8 +1,14 @@
|
||||
# Cài CASAN kiểu tool (global install + `casan init`) — Plan-21
|
||||
# Cài CASAN production (managed hoặc vendored Core) — 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.
|
||||
CASAN cài CLI/DevKit **một lần** vào máy (`$CASAN_HOME`). Mỗi project chạy
|
||||
`casan init` và chọn một runtime contract rõ ràng:
|
||||
|
||||
- `managed` (mặc định): Core nằm trong global install, project pin version/hash.
|
||||
- `vendored`: Core production-only nằm tại `.casan/runtime/casan-core`, dành
|
||||
cho offline, air-gapped hoặc repository cần self-contained.
|
||||
|
||||
Capability level và runtime placement là hai khái niệm độc lập. Project mặc
|
||||
định dùng Level 1/Core dù global package phải là DevKit để có lệnh `init`.
|
||||
|
||||
## 1. Cài đặt (một lần cho mỗi máy)
|
||||
|
||||
@@ -63,10 +69,19 @@ casan init # mặc định project Level 1/core; interacti
|
||||
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 init --runtime vendored --project offline-app --client claude,codex
|
||||
casan level show # xem level đã cài + level project
|
||||
casan level set 2 # đổi level project (không cần init lại)
|
||||
```
|
||||
|
||||
`init` và `level show` luôn in runtime mode/path. Project mới mặc định
|
||||
`managed`; chạy lại init giữ nguyên mode đã chọn. Chuyển mode phải explicit:
|
||||
|
||||
```bash
|
||||
casan init --runtime managed
|
||||
casan init --runtime vendored
|
||||
```
|
||||
|
||||
**Áp dụng cho dự án ĐÃ có vỏ (agents/skills/hook sẵn):** an toàn.
|
||||
- Mặc định `casan init` áp dụng **Level 1/core**: governance config + hooks,
|
||||
không thêm `.gitea` workflow hoặc domain-pack. Level cài global vẫn phải là
|
||||
@@ -89,7 +104,7 @@ nguyên checksum, sau đó prune thư mục rỗng. Workflow của project và s
|
||||
file đã chỉnh sửa được giữ lại. Thêm `--purge` để xóa cả runtime evidence
|
||||
`.specify/logs` và `.specify/state`.
|
||||
|
||||
`casan init` chỉ ghi **config per-project** (không copy harness):
|
||||
`casan init` luôn ghi config per-project:
|
||||
|
||||
| File | Vai trò |
|
||||
|---|---|
|
||||
@@ -101,6 +116,7 @@ file đã chỉnh sửa được giữ lại. Thêm `--purge` để xóa cả ru
|
||||
| `.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 |
|
||||
| `.casan/runtime/casan-core/` | Chỉ mode `vendored`: CLI + Core runtime production-only |
|
||||
|
||||
Tham số `--client` có thể lặp hoặc comma-separated:
|
||||
`claude`, `codex`, `vscode-copilot`, `all`, `none`. Khi chạy `casan init` trực
|
||||
@@ -154,7 +170,9 @@ Quy tắc migration:
|
||||
- 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`.
|
||||
Plan-20. Managed mode nâng cấp runtime ở `$CASAN_HOME`; vendored mode được nâng
|
||||
cấp có chủ đích bằng cách chạy lại `casan init --runtime vendored` từ release
|
||||
đã duyệt.
|
||||
|
||||
### Capability theo client
|
||||
|
||||
@@ -185,9 +203,10 @@ casan uninstall
|
||||
|
||||
Command này xóa CASAN project hooks, bootstrap và config nhưng giữ nguyên hook
|
||||
người dùng, CI/domain files, `.casan-bak`, VS Code extension dùng chung và
|
||||
`.specify` evidence. Dùng `--purge` nếu chủ động muốn xóa runtime logs/state;
|
||||
dùng `--remove-vscode-extension` nếu chắc chắn không project nào khác trên máy
|
||||
còn dùng route `@casan`.
|
||||
`.specify` evidence. Nếu project dùng vendored mode, toàn bộ
|
||||
`.casan/runtime/casan-core` cũng bị xóa. Dùng `--purge` nếu chủ động muốn xóa
|
||||
runtime logs/state; dùng `--remove-vscode-extension` nếu chắc chắn không project
|
||||
nào khác trên máy còn dùng route `@casan`.
|
||||
|
||||
## 3. Pin + Verify (giữ đảm bảo bảo mật khi harness ở ngoài repo)
|
||||
|
||||
@@ -209,18 +228,18 @@ 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ũ
|
||||
## 4. Chọn runtime mode
|
||||
|
||||
| | Vendored (`devkit/install.sh`) | Hybrid (`casan init`) |
|
||||
| | Vendored (`casan init --runtime vendored`) | Managed (`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) |
|
||||
| Repo | Tự chứa Core production-only | Nhẹ, chỉ config/lock/hooks |
|
||||
| Nâng cấp | Explicit theo từng repo | Tập trung ở `$CASAN_HOME` |
|
||||
| Bảo mật | Core local + **pin/hash verify** | Core global + **pin/hash verify** |
|
||||
| CI/offline | Phù hợp air-gapped | Runner phải cài đúng CASAN release |
|
||||
| Khuyến nghị | Khách hàng offline/regulated | Mặc định cho workstation và managed CI |
|
||||
|
||||
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.
|
||||
Cả hai dùng đúng cùng production allowlist và lõi harness; không mode nào mang
|
||||
theo tests, legacy `level5`, internal runners hay Platform-only helpers.
|
||||
|
||||
## 5. Kiểm thử
|
||||
|
||||
|
||||
@@ -1,131 +1,83 @@
|
||||
# CASAN Prompt Enforcement cho Agentic Coding
|
||||
# CASAN Prompt Enforcement
|
||||
|
||||
Tài liệu này mô tả ranh giới bắt buộc khi dùng Claude Code, Codex, GitHub Copilot Coding Agent hoặc agent plugin trong VS Code với project `__PROJECT_ID__`.
|
||||
CASAN thực thi governance qua integration native của từng client và một Core
|
||||
runtime đã pin theo project. Không dùng `bin/casan-chat` làm entrypoint bắt buộc
|
||||
cho project adoption mới.
|
||||
|
||||
## Contract
|
||||
## Luồng production
|
||||
|
||||
Một task chỉ được gọi là **CASAN-certified** khi:
|
||||
1. Developer gửi prompt trong client đã được project enable.
|
||||
2. Hook project gọi `.casan/casan-hook.py`.
|
||||
3. Bootstrap đọc `.casan/config.json` và `.casan/version.lock`.
|
||||
4. Core runtime được resolve theo mode `managed` hoặc `vendored`.
|
||||
5. Live hash phải khớp project pin trước khi adapter/gate được dispatch.
|
||||
6. Trace/evidence được ghi vào `.specify` của đúng project.
|
||||
|
||||
1. prompt đi vào `bin/casan-chat` hoặc `bin/casan-chat.ps1`;
|
||||
2. repository contract vượt qua `bin/casan prompt verify`;
|
||||
3. runtime tạo đủ evidence H1-H7;
|
||||
4. H7 trả `certified=true`;
|
||||
5. H6 telemetry có đúng `project_id=__PROJECT_ID__`;
|
||||
6. `bin/casan prompt trace <trace-id>` xác minh thành công.
|
||||
## Runtime mode
|
||||
|
||||
Prompt gõ trực tiếp vào cửa sổ agent mà không có CASAN trace không được coi là certified.
|
||||
Managed Core, khuyến nghị mặc định:
|
||||
|
||||
## Các lớp enforcement
|
||||
|
||||
### 1. Entrypoint
|
||||
|
||||
- macOS/Linux/WSL2: `bin/casan-chat`;
|
||||
- Windows PowerShell: `bin/casan-chat.ps1`;
|
||||
- launcher kiểm tra contract trước khi nhận prompt;
|
||||
- launcher chỉ trả exit code thành công khi trace của prompt đã được xác minh.
|
||||
|
||||
### 2. Repository instructions
|
||||
|
||||
Installer quản lý một block có marker trong:
|
||||
|
||||
- `AGENTS.md` cho Codex;
|
||||
- `CLAUDE.md` cho Claude Code;
|
||||
- `.github/copilot-instructions.md` cho GitHub Copilot.
|
||||
|
||||
Agent có đọc các instruction này phải từ chối thực hiện trực tiếp một task không đi qua CASAN và yêu cầu gửi lại qua launcher.
|
||||
|
||||
### 3. CI contract
|
||||
|
||||
`.gitea/workflows/casan-prompt-enforcement.yml` kiểm tra policy, launcher, instruction files, domain root và project binding. Workflow này độc lập, không ghi đè CI ứng dụng.
|
||||
|
||||
### 4. Per-prompt evidence
|
||||
|
||||
Mỗi prompt tạo trace tại:
|
||||
|
||||
```text
|
||||
.specify/logs/trace-events/<trace-id>.jsonl
|
||||
```bash
|
||||
casan init --project my-project --client claude,codex
|
||||
```
|
||||
|
||||
H6 runtime/token/cost/failure telemetry được ghi với `project_id=__PROJECT_ID__`.
|
||||
Core nằm trong `$CASAN_HOME`, còn project commit config/lock/bootstrap/hooks.
|
||||
|
||||
## Sử dụng hàng ngày
|
||||
Vendored Core cho offline/air-gapped:
|
||||
|
||||
Read-only/analysis mặc định:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1 "Analyze the current implementation against the approved requirement."
|
||||
```bash
|
||||
casan init --runtime vendored --project my-project --client claude,codex
|
||||
```
|
||||
|
||||
Chế độ tương tác:
|
||||
Core production-only nằm tại `.casan/runtime/casan-core`. Nếu folder này bị
|
||||
thiếu hoặc sai hash, CASAN fail closed; không fallback âm thầm sang global Core.
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1
|
||||
## Boundary theo client
|
||||
|
||||
### Claude Code
|
||||
|
||||
CASAN merge handler vào `.claude/settings.json`. Hook khác, agent, skill và key
|
||||
không thuộc CASAN được giữ nguyên.
|
||||
|
||||
### Codex
|
||||
|
||||
CASAN merge handler vào `.codex/hooks.json`. Người dùng phải mở `/hooks`, review
|
||||
và trust đúng hook hash của project.
|
||||
|
||||
### VS Code / GitHub Copilot
|
||||
|
||||
Route được chứng nhận là explicit `@casan`. CASAN không quảng bá rằng built-in
|
||||
Copilot Chat hoặc mọi prompt bên ngoài route này đều được intercept.
|
||||
|
||||
### Ngoài project
|
||||
|
||||
Prompt gửi trực tiếp vào website AI bên ngoài project/runtime không nằm trong
|
||||
boundary chứng nhận của CASAN. Kiểm soát website/proxy/identity ở cấp tổ chức là
|
||||
lớp bổ sung, không phải chức năng của repository hook.
|
||||
|
||||
## Kiểm tra
|
||||
|
||||
```bash
|
||||
casan doctor
|
||||
casan verify-harness
|
||||
casan level show
|
||||
```
|
||||
|
||||
## Coding task và quyền
|
||||
CI phải verify runtime pin trước gate:
|
||||
|
||||
Launcher mặc định dùng role `viewer`; role này không được sửa file hoặc chạy command tùy ý.
|
||||
|
||||
Người đã được cấp quyền tạo code draft có thể cấu hình phiên PowerShell:
|
||||
|
||||
```powershell
|
||||
$env:CASAN_CHAT_ROLE = 'project-admin'
|
||||
$env:CASAN_CHAT_AGENT = 'codegen-draft'
|
||||
$env:CASAN_CHAT_SKILL = 'sourcegen-draft'
|
||||
|
||||
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1 "Implement the approved task according to the current requirement and architecture."
|
||||
```bash
|
||||
casan verify-harness
|
||||
casan gate
|
||||
```
|
||||
|
||||
`codegen-draft` yêu cầu approval. Không tự đặt `project-admin` nếu chưa được cấp quyền. Side effect chỉ được thực thi bằng registered action hoặc `bin/casan run` theo policy hiện hành.
|
||||
Chỉ coi output là certified khi runtime integrity hợp lệ và trace H1–H7 tương
|
||||
ứng vượt qua policy.
|
||||
|
||||
Xóa biến sau phiên làm việc:
|
||||
## Gỡ integration
|
||||
|
||||
```powershell
|
||||
Remove-Item Env:CASAN_CHAT_ROLE -ErrorAction SilentlyContinue
|
||||
Remove-Item Env:CASAN_CHAT_AGENT -ErrorAction SilentlyContinue
|
||||
Remove-Item Env:CASAN_CHAT_SKILL -ErrorAction SilentlyContinue
|
||||
```bash
|
||||
casan uninstall
|
||||
```
|
||||
|
||||
## Kết quả hợp lệ
|
||||
|
||||
Một lượt thành công hiển thị tối thiểu:
|
||||
|
||||
```text
|
||||
CASAN decision=ANSWERED ... certified=true trace_id=<trace-id>
|
||||
CASAN evidence=<project>/.specify/logs/trace-events/<trace-id>.jsonl
|
||||
CASAN_PROMPT_TRACE_CERTIFIED project=__PROJECT_ID__ trace_id=<trace-id> gates=7
|
||||
```
|
||||
|
||||
Xác minh lại:
|
||||
|
||||
```powershell
|
||||
wsl -d Ubuntu -- bash -lc "cd '<project-wsl-path>' && bin/casan prompt trace '<trace-id>'"
|
||||
```
|
||||
|
||||
## Khi bị chặn
|
||||
|
||||
- `DENIED` hoặc `BLOCKED`: sửa prompt/context theo reason code; không bypass launcher.
|
||||
- `REQUIRES_APPROVAL`: gửi proposal cho người có quyền phê duyệt.
|
||||
- `CASAN_PROMPT_ENFORCEMENT_INVALID`: chạy lại installer từ CASAN Core mới nhất hoặc khôi phục managed artifact.
|
||||
- `trace_project_attribution_missing`: không sử dụng kết quả; kiểm tra `project_id` và H6 telemetry.
|
||||
- Plugin không đọc repository instructions: bật tính năng instruction hoặc chuyển sang công cụ được hỗ trợ.
|
||||
|
||||
## Kiểm tra nhanh đầu ngày
|
||||
|
||||
```powershell
|
||||
wsl -d Ubuntu -- bash -lc "cd '<project-wsl-path>' && bin/casan prompt verify"
|
||||
```
|
||||
|
||||
Kỳ vọng:
|
||||
|
||||
```text
|
||||
CASAN_PROMPT_ENFORCEMENT_VALID project=__PROJECT_ID__ mode=enforced
|
||||
```
|
||||
|
||||
## Điều không được làm
|
||||
|
||||
- Không gọi output trực tiếp của agent là CASAN-certified khi thiếu trace.
|
||||
- Không sửa/xóa evidence để thay đổi quyết định.
|
||||
- Không đổi role hoặc agent để né approval.
|
||||
- Không đưa secret, private key, token hoặc dữ liệu nhạy cảm vào prompt/context.
|
||||
- Không chạy command side effect ngoài registered action hoặc CASAN harness.
|
||||
Lệnh xóa CASAN hook/config và vendored Core nếu có, nhưng giữ hook/workflow/file
|
||||
project. Dùng `--purge` để xóa thêm `.specify` logs/state.
|
||||
|
||||
Reference in New Issue
Block a user