docs(devkit): ship Windows adoption guides
This commit is contained in:
thanhnv
@@ -0,0 +1,131 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user