132 lines
4.6 KiB
Markdown
132 lines
4.6 KiB
Markdown
# CASAN Prompt Enforcement cho Agentic Coding
|
|
|
|
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__`.
|
|
|
|
## Contract
|
|
|
|
Một task chỉ được gọi là **CASAN-certified** khi:
|
|
|
|
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.
|
|
|
|
Prompt gõ trực tiếp vào cửa sổ agent mà không có CASAN trace không được coi là certified.
|
|
|
|
## 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
|
|
```
|
|
|
|
H6 runtime/token/cost/failure telemetry được ghi với `project_id=__PROJECT_ID__`.
|
|
|
|
## Sử dụng hàng ngày
|
|
|
|
Read-only/analysis mặc định:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1 "Analyze the current implementation against the approved requirement."
|
|
```
|
|
|
|
Chế độ tương tác:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1
|
|
```
|
|
|
|
## Coding task và quyền
|
|
|
|
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."
|
|
```
|
|
|
|
`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.
|
|
|
|
Xóa biến sau phiên làm việc:
|
|
|
|
```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
|
|
```
|
|
|
|
## 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.
|