CASAN/docs/casan/CASAN_PROMPT_ENFORCEMENT.md

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:

.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 -ExecutionPolicy Bypass -File bin\casan-chat.ps1 "Analyze the current implementation against the approved requirement."

Chế độ tương tác:

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:

$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:

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:

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:

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

wsl -d Ubuntu -- bash -lc "cd '<project-wsl-path>' && bin/casan prompt verify"

Kỳ vọng:

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.