docs(devkit): ship Windows adoption guides
This commit is contained in:
thanhnv
@@ -0,0 +1,204 @@
|
||||
# Áp dụng CASAN từ đầu 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.
|
||||
|
||||
Giá trị sau được installer thay theo dự án:
|
||||
|
||||
- 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()
|
||||
```
|
||||
|
||||
Kiểm tra:
|
||||
|
||||
```powershell
|
||||
wsl -d Ubuntu -- bash -lc "test -d '$TargetProjectWsl' && printf 'TARGET_OK=%s\n' '$TargetProjectWsl'"
|
||||
```
|
||||
|
||||
Nếu dự án là Git repository, commit hoặc lưu riêng thay đổi hiện có trước khi adoption:
|
||||
|
||||
```powershell
|
||||
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && git status --short --branch"
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```powershell
|
||||
New-Item -ItemType Directory -Force -Path (Split-Path $CasanSourceWin -Parent) | Out-Null
|
||||
wsl -d Ubuntu -- bash -lc "git clone '$CasanRepo' '$CasanSourceWsl'"
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```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/
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 7. Xác minh installation contract
|
||||
|
||||
```powershell
|
||||
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && bin/casan prompt verify"
|
||||
```
|
||||
|
||||
Kết quả bắt buộc:
|
||||
|
||||
```text
|
||||
CASAN_PROMPT_ENFORCEMENT_VALID project=__PROJECT_ID__ mode=enforced
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 8. Chạy gate ban đầu
|
||||
|
||||
```powershell
|
||||
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && CASAN_DOMAIN_ROOT='apps/__PROJECT_ID__/domain' bin/casan gate"
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## 9. Gửi prompt qua CASAN
|
||||
|
||||
Từ project root trong PowerShell:
|
||||
|
||||
```powershell
|
||||
Set-Location $TargetProjectWin
|
||||
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1 "Review the current requirements and identify missing acceptance criteria."
|
||||
```
|
||||
|
||||
Chế độ tương tác:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1
|
||||
```
|
||||
|
||||
Mỗi lượt thành công phải có `certified=true`, `trace_id` và dòng `CASAN_PROMPT_TRACE_CERTIFIED ... gates=7`.
|
||||
|
||||
## 10. Xác minh một prompt
|
||||
|
||||
```powershell
|
||||
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && bin/casan prompt trace '<trace-id>'"
|
||||
```
|
||||
|
||||
Kết quả hợp lệ:
|
||||
|
||||
```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:
|
||||
|
||||
```powershell
|
||||
wsl -d Ubuntu -- bash -lc "cd '$TargetProjectWsl' && git status --short"
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
## 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.
|
||||
@@ -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.
|
||||
@@ -1,6 +1,6 @@
|
||||
# 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`. See [PROMPT_ENFORCEMENT_GUIDE.md](PROMPT_ENFORCEMENT_GUIDE.md) for the technical boundary and per-trace certification.
|
||||
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.
|
||||
|
||||
How a downstream project adopts the CASAN governance harness. Adoption is **config +
|
||||
domain only** — you never edit gate logic (H1→H7).
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 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).
|
||||
|
||||
The DevKit installer configures an adopted repository so supported repository agents and team members use CASAN as the certified prompt boundary.
|
||||
|
||||
## What is enforced
|
||||
|
||||
Reference in New Issue
Block a user