feat: add production Core runtime modes
This commit is contained in:
thanhnv
@@ -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