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.
|
||||
|
||||
@@ -1,33 +1,45 @@
|
||||
# CASAN Adoption Guide
|
||||
|
||||
The installer also provisions the mandatory prompt-enforcement pack. After adoption, send project prompts through `bin/casan-chat` (or `bin/casan-chat.ps1` on Windows/WSL2) and run `bin/casan prompt verify`. The canonical from-scratch guides are [CASAN_ADOPTION_WINDOWS.md](../casan/CASAN_ADOPTION_WINDOWS.md) and [CASAN_PROMPT_ENFORCEMENT.md](../casan/CASAN_PROMPT_ENFORCEMENT.md); the installer renders both into the target repository.
|
||||
CASAN separates machine installation from project adoption. Install the DevKit
|
||||
once so the `casan` command is available, then enroll each repository with a
|
||||
version/hash lock. Application teams never edit gate logic (H1→H7).
|
||||
|
||||
How a downstream project adopts the CASAN governance harness. Adoption is **config +
|
||||
domain only** — you never edit gate logic (H1→H7).
|
||||
## Option A — Managed Core (recommended)
|
||||
|
||||
## Option A — DevKit install (recommended)
|
||||
|
||||
Clone CASAN Core from your Gitea repository once, and pull the latest `main` before each install or upgrade:
|
||||
Install from an approved checkout or release:
|
||||
|
||||
```bash
|
||||
git clone <gitea-casan-core-url> casan-core
|
||||
cd casan-core
|
||||
git pull --ff-only origin main
|
||||
sh install.sh --level devkit
|
||||
cd /path/to/my-project
|
||||
casan init --project ticketing --client claude,codex
|
||||
casan doctor
|
||||
casan verify-harness
|
||||
```
|
||||
|
||||
Then run the installer from that CASAN checkout:
|
||||
The project defaults to Level 1/Core with runtime mode `managed`. Core remains
|
||||
under `$CASAN_HOME`; the repository receives `.casan` config/lock/bootstrap and
|
||||
the selected client hooks. The CLI output states the resolved runtime path.
|
||||
|
||||
Use this for developer workstations and managed CI runners. CI must install the
|
||||
same release recorded by `.casan/version.lock` before running gates.
|
||||
|
||||
## Option B — Vendored Core (offline/self-contained)
|
||||
|
||||
```bash
|
||||
packages/casan-devkit/install.sh --target ../my-project --project ticketing --domain "Ticketing"
|
||||
cd /path/to/my-project
|
||||
casan init --runtime vendored --project ticketing --client claude,codex
|
||||
casan doctor
|
||||
casan verify-harness
|
||||
```
|
||||
This copies the core harness + `bin/casan` into `../my-project`, scaffolds
|
||||
`apps/ticketing/domain/` from the domain-pack template, installs the prompt entrypoints and
|
||||
standalone `.gitea/workflows/casan-prompt-enforcement.yml`, and registers the project in
|
||||
`project-registry.json`. Existing domain files, registry state, and project CI are preserved.
|
||||
The copied harness follows the production allowlist and excludes CASAN's own tests,
|
||||
legacy `level5/`, internal CI runners, and Platform-only helpers.
|
||||
|
||||
## Option A2 — New production project shell
|
||||
This installs the production-only Core at
|
||||
`.casan/runtime/casan-core/`, including a local `bin/casan`. It excludes tests,
|
||||
legacy `level5`, internal runners and Platform helpers. Choose this for
|
||||
air-gapped customers or repositories that must execute without a machine-level
|
||||
runtime. Re-running init preserves the selected mode; switching mode requires
|
||||
an explicit `--runtime managed|vendored`.
|
||||
|
||||
## Option C — New production project shell
|
||||
|
||||
```bash
|
||||
packages/casan-devkit/install.sh \
|
||||
@@ -41,16 +53,10 @@ This creates a strict-TypeScript NestJS/React monorepo, health bootstrap, tests,
|
||||
images, GitHub CI, a complete Domain Pack, versioned quality profile, project manifest, CASAN CLI,
|
||||
harness, and manifest-driven pipeline. Existing different files are never overwritten.
|
||||
|
||||
## Option B — Core tarball (harness-only / CI gate)
|
||||
```bash
|
||||
tar -xzf casan-core-v1.0.0.tar.gz
|
||||
cp -R casan-core-v1.0.0/{packages,bin,VERSION} /path/to/project/
|
||||
```
|
||||
Then create `apps/<project>/domain/` yourself (see `DOMAIN_PACK_GUIDE.md`).
|
||||
This harness-only option does not install the mandatory repository prompt-enforcement pack;
|
||||
use Option A when every project prompt must be governed and certifiable.
|
||||
The legacy direct installer is reserved for generating a new application shell;
|
||||
do not use it merely to enroll an existing repository.
|
||||
|
||||
## Option C — Docker (no install into repo)
|
||||
## Option D — Docker (no install into repo)
|
||||
```bash
|
||||
docker run --rm -v "$PWD":/workspace -w /workspace casan-harness:1.0.0 casan gate
|
||||
```
|
||||
@@ -77,11 +83,13 @@ bin/casan pipeline --manifest apps/<project>/domain/project.manifest.json
|
||||
```
|
||||
|
||||
## Path model (what lives where)
|
||||
- **Harness code** → `packages/casan-harness/` (never edited by adopters).
|
||||
- **Managed Core** → `$CASAN_HOME/current/packages/casan-harness/`.
|
||||
- **Vendored Core** → `.casan/runtime/casan-core/packages/casan-harness/`.
|
||||
- **Project lock/config** → `.casan/config.json` and `.casan/version.lock`.
|
||||
- **Your domain data** → `apps/<project>/domain/` (via `CASAN_DOMAIN_ROOT`).
|
||||
- **Runtime state** → `.specify/` (logs, audit, governance — created on first run).
|
||||
Paths resolve via `packages/casan-harness/scripts/bash/casan-paths.sh` (marker walk-up:
|
||||
`.specify` or `packages/casan-harness`), so a freshly-extracted bundle works immediately.
|
||||
The bootstrap resolves the mode/path from the project lock and verifies the live
|
||||
Core hash before dispatch.
|
||||
|
||||
## Proving reuse
|
||||
Two+ projects sharing the same harness package/version → `bin/casan reuse` prints
|
||||
|
||||
@@ -1,69 +1,92 @@
|
||||
# CASAN Prompt Enforcement for Adopted Projects
|
||||
|
||||
For the canonical agentic-coding guide installed into downstream repositories, see [`docs/casan/CASAN_PROMPT_ENFORCEMENT.md`](../casan/CASAN_PROMPT_ENFORCEMENT.md). For a full Windows installation starting from a repository with no CASAN files, see [`docs/casan/CASAN_ADOPTION_WINDOWS.md`](../casan/CASAN_ADOPTION_WINDOWS.md).
|
||||
CASAN adopts existing repositories through native project hooks. The global
|
||||
DevKit provides `casan init`; each project pins either a managed or vendored
|
||||
Core runtime.
|
||||
|
||||
The DevKit installer configures an adopted repository so supported repository agents and team members use CASAN as the certified prompt boundary.
|
||||
## Supported boundaries
|
||||
|
||||
## What is enforced
|
||||
- Claude Code: project hooks in `.claude/settings.json`.
|
||||
- Codex: project hooks in `.codex/hooks.json`, subject to explicit `/hooks`
|
||||
review and trust.
|
||||
- VS Code/Copilot: CASAN-owned explicit `@casan` route.
|
||||
|
||||
- `bin/casan-chat` is the macOS/Linux/WSL2 prompt entrypoint.
|
||||
- `bin/casan-chat.ps1` is the Windows wrapper and executes the same entrypoint through WSL2.
|
||||
- `.casan/prompt-policy.json` binds prompts and H6 telemetry to one `project_id`.
|
||||
- `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` tell supported repository agents to refuse direct prompt work and require resubmission through CASAN.
|
||||
- The standalone `.gitea/workflows/casan-prompt-enforcement.yml` workflow verifies that the policy, launchers, instructions, domain root, and workflow contract are present and have not been stripped. Existing project CI is not overwritten.
|
||||
- A certified prompt must produce a trace with passing H1-H7 gates and H6 telemetry attributed to the configured project.
|
||||
CASAN does not claim to intercept arbitrary prompts typed into external web
|
||||
sites or built-in Copilot Chat outside the explicit `@casan` route.
|
||||
|
||||
## Enforcement boundary
|
||||
## Install
|
||||
|
||||
A repository cannot technically intercept text typed directly into an external ChatGPT, Claude, or Copilot website. Such conversations are outside the CASAN runtime and therefore are **not CASAN-certified**. The enforceable rule is:
|
||||
|
||||
1. Use a CASAN-owned entrypoint for every project prompt.
|
||||
2. Repository-aware agents must refuse direct execution when their instruction file is loaded.
|
||||
3. Accept governed output only when its CASAN trace passes verification.
|
||||
|
||||
For stronger organizational control, restrict direct external AI sites at the identity, proxy, or network layer. That control is outside the repository and complements CASAN rather than replacing its H1-H7 evidence.
|
||||
|
||||
## Install or upgrade
|
||||
|
||||
From a checked-out CASAN Core repository:
|
||||
Install the DevKit once:
|
||||
|
||||
```bash
|
||||
packages/casan-devkit/install.sh \
|
||||
--target "/absolute/path/to/existing-project" \
|
||||
--project "project-id" \
|
||||
--domain "Project display name"
|
||||
sh install.sh --level devkit
|
||||
```
|
||||
|
||||
The installer is idempotent for the managed instruction blocks. Existing content outside the CASAN markers, project domain documents, project registry, and existing CI workflows is retained.
|
||||
|
||||
## Send prompts
|
||||
|
||||
macOS, Linux, or WSL2:
|
||||
Adopt an existing project with the recommended managed Core:
|
||||
|
||||
```bash
|
||||
bin/casan-chat "Review the current requirements and identify missing acceptance criteria"
|
||||
cd /absolute/path/to/existing-project
|
||||
casan init --project project-id --client claude,codex
|
||||
casan doctor
|
||||
casan verify-harness
|
||||
```
|
||||
|
||||
Windows PowerShell with WSL2:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1 "Review the current requirements"
|
||||
```
|
||||
|
||||
Run without a prompt to enter interactive mode.
|
||||
|
||||
## Verify
|
||||
|
||||
Verify the repository contract:
|
||||
For an offline/self-contained repository:
|
||||
|
||||
```bash
|
||||
bin/casan prompt verify
|
||||
casan init --runtime vendored --project project-id --client claude,codex
|
||||
```
|
||||
|
||||
Verify an individual governed result:
|
||||
Vendored Core is installed under `.casan/runtime/casan-core` using the same
|
||||
production allowlist as the global release. Tests, legacy `level5`, internal
|
||||
runners and Platform-only helpers are excluded.
|
||||
|
||||
## Runtime contract
|
||||
|
||||
`.casan/config.json` records:
|
||||
|
||||
- project ID and enforcement mode;
|
||||
- selected client integrations;
|
||||
- project capability level;
|
||||
- runtime mode and path.
|
||||
|
||||
`.casan/version.lock` records the exact Core version and integrity hash.
|
||||
`casan verify-harness` recomputes the live hash; it does not trust a cached
|
||||
value. Vendored mode fails closed if the local Core is absent instead of
|
||||
silently falling back to global Core.
|
||||
|
||||
## Existing repository safety
|
||||
|
||||
`casan init` merges only CASAN handlers into supported client configuration.
|
||||
Existing hooks, agents, skills, instructions and CI workflows are preserved.
|
||||
Re-running init is idempotent and preserves the selected runtime mode unless
|
||||
`--runtime managed|vendored` is explicitly supplied.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
bin/casan prompt trace <trace-id>
|
||||
casan doctor
|
||||
casan verify-harness
|
||||
casan level show
|
||||
```
|
||||
|
||||
Only the second command proves that the individual prompt completed H1-H7 and has matching H6 project telemetry.
|
||||
For Codex, open `/hooks`, review the exact project hook and trust its hash.
|
||||
|
||||
For CI, verify the pin before executing governance gates:
|
||||
|
||||
```bash
|
||||
casan verify-harness
|
||||
casan gate
|
||||
```
|
||||
|
||||
## Uninstall
|
||||
|
||||
```bash
|
||||
casan uninstall
|
||||
```
|
||||
|
||||
This removes CASAN hooks/config, CASAN-owned Gitea workflows, unchanged CASAN
|
||||
scaffold files and vendored Core. User-authored hooks/workflows and modified
|
||||
project files are retained. Add `--purge` to remove `.specify` logs/state, and
|
||||
use `--remove-vscode-extension` only when the shared extension is no longer
|
||||
needed by any project.
|
||||
|
||||
Reference in New Issue
Block a user