CASAN/README.md

# CASAN

CASAN là governance harness cho agentic coding. CASAN bổ sung policy gates,
audit trail, evidence và kiểm tra integrity vào lifecycle của coding agent,
nhưng không thay thế IDE, model, agent, skill, slash command hay workflow hiện
có của repository.

Mô hình production mặc định:

- Cài **DevKit một lần trên máy** để có launcher và lệnh quản trị.
- Chạy `casan init` trong từng repository.
- Project mới dùng **Core edition + Managed runtime + Enforce mode** nếu người
  dùng không chọn khác.
- Project offline, air-gapped hoặc cần tự chứa runtime có thể chọn
  **Vendored runtime**.

`casan init` chỉ thêm lớp tích hợp cần thiết. Runtime phát hành không chứa test
suite, test scripts, internal CI runners, `level5`, dashboard lab, source docs
hay release tooling.

## Trạng thái sản phẩm

| Thành phần | Trạng thái | Phạm vi |
|---|---|---|
| Core | Implemented | H1–H7 harness, hooks, policy gates, audit, evidence, CLI và Local Assurance Viewer |
| DevKit | Implemented | Core + adoption tooling, domain-pack và CI template |
| Control Plane | Preview | Live H1–H7, H6, run history và evidence export; deploy riêng |
| Enterprise | Chưa phát hành | OIDC/KMS/WORM/HA/DR/SLA; CLI chủ động từ chối |

Tên edition không phải maturity score. **CASAN Maturity L1–L5** là kết quả đánh
giá dựa trên evidence vận hành; cài Core không tự động có nghĩa là maturity L1,
và cài Control Plane không tự động đạt L3/L4.

## Bốn quyết định cần phân biệt

CASAN tách riêng bốn khái niệm để cấu hình rõ ràng:

| Quyết định | Lựa chọn | Mặc định production |
|---|---|---|
| Gói cài trên máy | `core`, `devkit`, `platform` | `devkit`, vì `casan init` thuộc DevKit |
| Product edition | `--edition core`, `devkit`, `platform-preview` | `core` |
| Vị trí Core runtime | `--runtime managed`, `vendored` | `managed` |
| Cách thực thi policy | `--mode enforce`, `observe` | `enforce` |

`--edition core` không có nghĩa Core phải nằm trong repository. Edition mô tả
capability được đóng gói; runtime mô tả vị trí; maturity mô tả mức vận hành đã
được chứng minh. Đây là ba trục độc lập. `--level` vẫn được giữ như alias cũ.

## Golden path: prompt → live assurance

Core không export HTML và không giữ web server trên hot path. Sau mỗi prompt,
hook chỉ ghi trace/H6 và trả assurance receipt. Khi cần xem, `casan view` khởi
động/reuse **Local Assurance Viewer** read-only trên loopback và mở đúng run.
Viewer, H1–H7, H6, history và export đều nằm trong Core, hoạt động offline,
không cần Node/npm hoặc Platform.

```bash
# Sau một prompt
casan report latest
casan view                              # mở run mới nhất trong Core viewer
casan report export --format html      # run dossier, chỉ tạo khi được yêu cầu
casan report export --h6 --format html # H6 dossier on-demand

# Lifecycle viewer cục bộ
casan dashboard status
casan dashboard stop
```

Không cần chạy `export` sau mỗi prompt. Evidence là source of truth; HTML/JSON
chỉ là projection on-demand. `casan dashboard start` trong Core mở viewer
single-project. Khi bundle Platform hiện diện, cùng lệnh đó quản lý Control
Plane. Production triển khai Platform như service dùng chung chỉ khi cần
multi-project, RBAC tập trung, approvals và fleet operations.

## Quick start

### Yêu cầu

- macOS/Linux: Python 3 và Bash.
- Windows: PowerShell 5.1+, Python 3 và Git for Windows/Git Bash.
- Client tương ứng nếu cần: Claude Code, Codex hoặc VS Code.

### 1. Cài DevKit một lần trên máy

Từ checkout hoặc release bundle đã được duyệt:

```bash
# macOS/Linux
sh install.sh --level devkit

# Chỉ cần nếu terminal hiện tại chưa nhận launcher
export PATH="${CASAN_HOME:-$HOME/.casan}/bin:$PATH"

casan version
```

```powershell
# Windows PowerShell
pwsh .\install.ps1

# Mở terminal mới sau khi installer cập nhật user PATH
casan version
```

Vị trí mặc định:

- macOS/Linux: `~/.casan`
- Windows: `%LOCALAPPDATA%\casan`

Có thể đặt `CASAN_HOME` trước khi cài nếu tổ chức dùng một vị trí quản lý khác.
`casan init` không hỏi một đường dẫn runtime tùy ý: Managed luôn dùng
installation đã resolve từ `CASAN_HOME`; Vendored luôn dùng
`.casan/runtime/casan-core` trong project.

### 2. Khởi tạo CASAN trong repository

```bash
cd <project-root>
casan init
```

Với project mới và terminal tương tác, wizard hỏi hai lựa chọn:

```text
Core runtime placement

  1) Managed (Recommended)
     Use the shared CASAN installation, pinned by version and hash.
     Best for developer workstations and managed CI.

  2) Vendored
     Copy production-only Core into .casan/runtime/casan-core.
     Best for offline, air-gapped, or self-contained repositories.

Select runtime [1]:

Client integrations

  1) Claude Code
  2) Codex
  3) GitHub Copilot in VS Code via explicit @casan route

Select clients (comma-separated) [1,2]:
```

Nhấn Enter để dùng Managed và Claude Code + Codex. Nhập sai sẽ được hướng dẫn
chọn lại. Sau khi hoàn tất, output terminal là bản tóm tắt dễ đọc gồm project,
edition, maturity status, runtime, mode, client, file thay đổi và next steps.

Project đã init không bị hỏi lại runtime: CASAN giữ nguyên mode hiện tại. Muốn
đổi, truyền rõ `--runtime managed` hoặc `--runtime vendored`.

### 3. Kiểm tra readiness

```bash
casan doctor
casan verify-harness
casan edition show
```

Với Codex, mở `/hooks`, review và trust đúng project hook sau lần init hoặc khi
bootstrap hash thay đổi.

Codex hooks gọi bootstrap tương đối từ project root và không phụ thuộc vào
`git rev-parse`, nên ownership hoặc cấu hình Git không thể làm hỏng lifecycle
hook. Git vẫn được khuyến nghị mạnh cho source provenance, review diff và
rollback trước khi cho agent thực hiện side effect.

### 4. Dùng workflow hiện có

Tiếp tục dùng chat, agents, skills và slash commands của project như bình
thường. Không cần gọi một “CASAN agent” hoặc chạy một pipeline CASAN riêng.

CASAN tham gia tại lifecycle của client đã enable:

1. `UserPromptSubmit`: admission và quét prompt.
2. `PreToolUse`: kiểm tra tool input, chặn side effect không hợp lệ.
3. `PostToolUse`: ghi evidence của tool result.
4. `Stop`: finalize trace, telemetry và trạng thái certification.

CASAN bridge không gọi model lần thứ hai. Claude Code hoặc Codex vẫn là model
executor duy nhất.

## Dùng trong script và CI

Automation phải khai báo quyết định rõ ràng:

```bash
casan init \
  --non-interactive \
  --level core \
  --runtime managed \
  --mode enforce \
  --client claude,codex
```

`--non-interactive` và `--json` không bao giờ chờ input. Nếu không truyền
`--runtime`, project mới mặc định Managed; nếu không truyền `--client`, mặc
định Claude Code + Codex để tương thích các bản trước.

Output mặc định dành cho người đọc. Chỉ dùng JSON khi một chương trình cần xử
lý dữ liệu:

```bash
casan init --non-interactive --client codex --json
casan doctor --json
casan verify-harness --json
casan level show --json
```

## Chọn runtime

### Managed — khuyến nghị cho đa số tổ chức

Managed dùng Core trong global installation và pin version/hash theo từng
project.

Ưu điểm:

- Repository nhẹ, không nhân bản runtime.
- Nâng cấp và rollback tập trung.
- Phù hợp workstation và CI runner được quản lý.
- Nhiều project có thể dùng chung một CASAN installation.

Yêu cầu:

- Máy developer/runner phải cài release CASAN mà project đã pin.
- Không thay runtime global tùy tiện; luôn chạy `casan verify-harness`.

```bash
casan init --runtime managed
```

### Vendored — cho môi trường tự chứa

Vendored copy Core production-only vào
`.casan/runtime/casan-core`. Bootstrap và launcher trong project resolve runtime
này trước, không âm thầm fallback sang global nếu runtime bị thiếu.

Ưu điểm:

- Có thể hoạt động offline hoặc air-gapped.
- Runtime đi cùng đúng project.
- Phù hợp repository được đóng gói thành một deliverable độc lập.

Đánh đổi:

- Repository/artifact lớn hơn.
- Mỗi project phải chủ động nhận bản vá và upgrade.
- Tổ chức phải quản lý quyền phân phối runtime theo license.

```bash
casan init --runtime vendored
```

### Bảng quyết định

| Tình huống | Runtime nên dùng |
|---|---|
| Máy developer và CI do công ty quản lý | Managed |
| Nhiều repository dùng chung CASAN | Managed |
| Cần rollout/rollback tập trung | Managed |
| Offline hoặc air-gapped | Vendored |
| Deliverable phải tự chứa toàn bộ Core | Vendored |
| Không thể đảm bảo CASAN đã cài trên runner | Vendored |

## Chọn project level

| Level | Dùng khi | Nội dung thêm vào project |
|---|---|---|
| `core` | Mặc định cho repository đã có cấu trúc | Governance Core, bootstrap, hooks và config |
| `devkit` | Cần CASAN domain-pack và CI template | Core + `.gitea/workflows/casan-ci.yml` + domain scaffold |
| `platform` | Đánh giá Platform preview | Áp dụng nền Level 2; Control Panel vẫn deploy riêng |
| `enterprise` | Chưa khả dụng | CLI từ chối |

```bash
casan init --level core
casan init --level devkit
```

Level 1 Core không đưa test folders, test scripts, `level5` hoặc source-only
components vào project. Chỉ chọn DevKit khi thực sự cần scaffold bổ sung.

## Enforcement mode

| Mode | Dùng cho | Hành vi |
|---|---|---|
| `enforce` | Production | Side effect fail-closed; turn đủ evidence có thể certified |
| `observe` | Pilot và thu telemetry | Ghi nhận nhưng không chặn như production; luôn `observed_only` |

```bash
casan init --mode enforce
casan init --mode observe
```

Không gọi một turn là CASAN-certified nếu không có trace tương ứng hoặc trace bị
đánh dấu `observed_only`/`non_certified`.

## Client support

| Client surface | Chat bình thường tự qua CASAN | Bước bắt buộc |
|---|---:|---|
| Claude Code CLI | Có | Mở repository dưới dạng trusted project |
| Claude Code trong VS Code / JetBrains | Có | Dùng project `.claude/settings.json`; mở trusted project |
| Codex desktop app — Local | Có | Mở `/hooks`, review và trust hook hash |
| Codex CLI / IDE extension — Local | Có | Mở `/hooks`, review và trust hook hash |
| Codex Cloud / Web | Chưa | Project hook local không phải cloud enforcement boundary |
| Claude Desktop / claude.ai | Chưa | Không chạy Claude Code project hooks |
| GitHub Copilot Chat | Không tự động | Cài CASAN VSIX và gửi `@casan <prompt>` |

`--client claude` cấu hình **Claude Code runtime**, dùng chung cho CLI, VS Code
extension và JetBrains integration. `--client codex` cấu hình **Codex local
runtime**, dùng chung cho desktop app, CLI và IDE extension. CASAN không tạo
adapter trùng lặp theo từng UI; cùng một project hook và cùng một integrity pin
được dùng trên các local surface.

Các cách chọn client:

```bash
casan init --client claude
casan init --client codex
casan init --client claude,codex
casan init --client vscode-copilot --vscode-install yes
casan init --client all
casan init --client none
```

GitHub Copilot không cung cấp public API để extension intercept toàn bộ built-in
chat. Chỉ route explicit `@casan` mới là CASAN-owned. Backend tự gọi LLM API
cũng không đi qua IDE hooks và cần adapter riêng.

## Kiến trúc runtime

```mermaid
flowchart TB
  U["Developer"] --> C["Claude Code / Codex / @casan"]
  C --> B["Project bootstrap<br/>.casan/casan-hook.py"]
  B --> R{"Runtime mode"}
  R -- "Managed" --> GM["CASAN_HOME/current"]
  R -- "Vendored" --> GV[".casan/runtime/casan-core"]
  GM --> V{"Version + hash<br/>match version.lock?"}
  GV --> V
  V -- "No" --> D["Deny or degrade<br/>according to enforcement mode"]
  V -- "Yes" --> A["Client adapter"]
  A --> G["Agentic bridge"]
  G --> L1["Admission"]
  L1 --> L2["Pre-tool gate"]
  L2 --> L3["Post-tool evidence"]
  L3 --> L4["Finalize trace"]
  L4 --> S[".specify/logs + state"]
  L4 --> O["Native client result"]
```

Runtime resolution fail-closed: một project pin Vendored nhưng thiếu
`.casan/runtime/casan-core` sẽ báo lỗi và yêu cầu restore bằng release DevKit đã
duyệt, không tự chuyển sang Managed.

## Cấu trúc cài đặt

### Global installation

```text
CASAN_HOME/
├── bin/casan
├── current -> versions/<version>
└── versions/<version>/
    ├── VERSION
    ├── bin/casan
    ├── packages/casan-harness/
    └── packages/casan-devkit/
```

Release runtime là allowlist production-only. Tests và release tooling vẫn nằm
trong source repository để kiểm chứng CASAN, nhưng không được copy vào
installation hoặc project runtime.

### Project sau `casan init`

```text
<project>/
├── .casan/
│   ├── config.json
│   ├── version.lock
│   ├── casan-hook.py
│   ├── agentic.env
│   ├── init-manifest.json
│   └── runtime/casan-core/       # chỉ khi --runtime vendored
├── .specify/
│   ├── .gitignore
│   ├── logs/                     # runtime, không commit
│   └── state/                    # runtime, không commit
├── .claude/settings.json         # khi enable Claude
├── .codex/hooks.json             # khi enable Codex
├── .vscode/extensions.json       # merge theo client
└── .gitea/workflows/casan-ci.yml # chỉ Level 2, nếu chưa có
```

### File nào được thay đổi

| Path | Hành vi |
|---|---|
| `.casan/config.json` | Project id, level, runtime mode, enforcement mode và clients |
| `.casan/version.lock` | Pin version và SHA-256 của Core runtime đã resolve |
| `.casan/casan-hook.py` | Stdlib bootstrap, verify pin rồi dispatch adapter |
| `.casan/agentic.env` | Compatibility/reference flags; runtime đọc `config.json` |
| `.casan/init-manifest.json` | Danh sách file CASAN quản lý, checksum và backup |
| `.casan/runtime/casan-core/` | Core production-only; chỉ có ở Vendored |
| `.specify/logs`, `.specify/state` | Trace, audit và state runtime; không commit |
| `.claude/settings.json` | Merge CASAN handlers khi enable Claude |
| `.codex/hooks.json` | Merge CASAN handlers khi enable Codex |
| `.vscode/extensions.json` | Merge extension recommendations theo client |
| `.gitea/workflows/casan-ci.yml` | Chỉ Level 2; chỉ tạo khi chưa có |
| `apps/<project-id>/domain/` | Chỉ Level 2; chỉ bổ sung file còn thiếu |

Trước lần thay đổi đầu tiên, init tạo `<file>.casan-bak` cho file hiện hữu.
`init-manifest.json` giúp re-init và uninstall chỉ quản lý đúng tài sản CASAN.

### Nội dung luôn được bảo toàn

- Source code và cấu trúc ứng dụng.
- `.claude/agents`, `.claude/skills`, `.claude/commands`.
- Agents, skills, prompts và instructions trong `.github/`.
- Hook, JSON key và VS Code recommendation không thuộc CASAN.
- CI/workflow hiện hữu.
- Scaffold file đã được người dùng chỉnh sửa.
- Backup `.casan-bak`.

CASAN source hub tự từ chối self-adoption. Không dùng `--force` trừ khi chủ động
kiểm thử trường hợp này.

## Nên commit gì

Thông thường nên commit:

- `.casan/config.json`
- `.casan/version.lock`
- `.casan/casan-hook.py`
- `.casan/agentic.env`
- `.casan/init-manifest.json`
- các client config đã merge
- Level 2 workflow/domain files sau khi review

Không commit:

- `.specify/logs/`
- `.specify/state/`
- file `.casan-bak`

Với Managed, không có runtime để commit. Với Vendored, tổ chức phải đưa
`.casan/runtime/casan-core` vào cùng deliverable bằng Git hoặc artifact channel
đã duyệt; nếu bỏ runtime này, project sẽ fail-closed. Quyết định phân phối phải
tuân theo license và policy nội bộ.

## Cấu hình lại

Chạy lại init với **toàn bộ danh sách client mong muốn**:

```bash
# Chỉ giữ Claude
casan init --client claude

# Tắt CASAN IDE integrations nhưng giữ config và evidence
casan init --client none

# Chuyển runtime có chủ đích
casan init --runtime vendored
casan init --runtime managed
```

Client bị bỏ khỏi danh sách sẽ được gỡ CASAN handler; hook và config không thuộc
CASAN vẫn được giữ. `--client none` không tự gỡ VS Code extension dùng chung.

## Nâng cấp và rollback

### Managed

1. Cài release CASAN đã duyệt trên workstation/runner.
2. Chạy lại `casan init --runtime managed` trong từng project để cập nhật
   bootstrap và pin.
3. Chạy `casan doctor` và `casan verify-harness`.
4. Với Codex, review/trust lại hook nếu hash thay đổi.

### Vendored

1. Cài hoặc giải nén DevKit release đã duyệt trên máy thực hiện upgrade.
2. Chạy `casan init --runtime vendored`; CASAN refresh Core production-only
   trong project.
3. Review thay đổi runtime, chạy `doctor` và `verify-harness`.
4. Phát hành lại deliverable Vendored.

Rollback dùng đúng release đã duyệt trước đó, chạy lại init và verify. Không bỏ
qua `HARNESS_INTEGRITY_DRIFT` trong production.

## Uninstall

```bash
# Gỡ hooks, config, CASAN workflow/scaffold còn nguyên checksum và Vendored Core
casan uninstall

# Đồng thời xóa runtime evidence
casan uninstall --purge

# Chỉ khi VSIX dùng chung không còn cần trên máy
casan uninstall --remove-vscode-extension
```

`casan uninstall`:

- gỡ CASAN handlers nhưng giữ handlers của project;
- xóa CASAN-owned `.gitea` workflow và dọn thư mục cha nếu đã rỗng;
- xóa `.casan/runtime/casan-core` nếu dùng Vendored;
- chỉ xóa scaffold file còn đúng checksum;
- giữ file người dùng đã sửa và `.casan-bak`;
- giữ `.specify/logs` và `.specify/state` trừ khi có `--purge`;
- không mặc định gỡ VSIX vì extension có thể được project khác dùng chung.

Sau uninstall, output liệt kê rõ mục đã xóa và mục được giữ lại.

## CI production

Gate tối thiểu:

```bash
casan verify-harness
casan gate
```

Managed runner phải cài đúng approved release trước khi chạy gate. Vendored
runner phải nhận `.casan/runtime/casan-core` cùng checkout/artifact; global
launcher vẫn có thể được dùng, nhưng runtime policy được resolve từ project.

Level 2 tạo `.gitea/workflows/casan-ci.yml` như một template nếu file chưa tồn
tại. Luôn review template theo runner, secret model và runtime mode của tổ chức
trước khi enable. CASAN không ghi đè workflow hiện hữu.

Đảm bảo `.specify/logs/` và `.specify/state/` không được commit. Init chỉ tạo
`.specify/.gitignore` khi file đó chưa tồn tại.

## CLI tham khảo

| Lệnh | Mục đích |
|---|---|
| `casan init` | Adopt hoặc cấu hình lại CASAN trong project |
| `casan uninstall` | Gỡ CASAN-owned project integration an toàn |
| `casan doctor` | Kiểm tra config, bootstrap, pin, adapters và client readiness |
| `casan verify-harness` | So live Core hash với project pin |
| `casan level show` | Hiển thị installed level, project level và runtime |
| `casan gate` | Chạy production checks từ project manifest |
| `casan verify` | Verify audit chain, tool audit và policy bundle |
| `casan prompt verify` | Verify prompt-enforcement contract |
| `casan prompt trace <trace-id>` | Verify H1–H7 certification của một turn |
| `casan version` | Hiển thị phiên bản |
| `casan help` | Hiển thị toàn bộ command |

Các trạng thái quan trọng:

- `doctor` trả non-zero khi project chưa sẵn sàng.
- `verify-harness` trả exit code `3` khi phát hiện drift.
- Cú pháp/giá trị CLI không hợp lệ trả exit code `64`.
- JSON là opt-in qua `--json`; lỗi vận hành vẫn được viết ngắn gọn ra stderr.

## Troubleshooting

### `casan` không có trên PATH

Mở terminal mới hoặc thêm `${CASAN_HOME:-$HOME/.casan}/bin` vào `PATH`.

### Managed báo integrity drift

Cài đúng release đã pin, chạy lại `casan init --runtime managed`, sau đó
`casan verify-harness`. Không sửa `version.lock` thủ công để né kiểm tra.

### Vendored báo runtime missing

Từ một approved DevKit installation, chạy:

```bash
casan init --runtime vendored
casan verify-harness
```

### Codex chưa chạy hook

Mở `/hooks`, review project hook và trust hash hiện tại.

### GitHub Copilot chat không tự qua CASAN

Dùng explicit route `@casan <prompt>` và kiểm tra
`fpt-casan.casan-governed-chat` đã được cài.

## Cấu trúc source repository CASAN

| Path | Trách nhiệm |
|---|---|
| `bin/casan` | CLI entrypoint |
| `install.sh`, `install.ps1` | Global installers |
| `packages/casan-harness/` | Runtime controls, adapters, policies, evidence và source tests |
| `packages/casan-devkit/` | Project adoption tooling và templates |
| `packages/casan-control-panel/` | Platform UI/API preview, deploy riêng |
| `packaging/levels.json` | Nguồn sự thật cho package level và maturity |
| `infra/` | Local/production deployment references |
| `docs/` | Security, operations, packaging và design records |
| `apps/` | Demo/validation applications; không phải runtime dependency của `casan init` |

Source tree có tests để phát triển sản phẩm. Release packaging dùng allowlist để
chỉ đưa production runtime cần thiết vào global install hoặc Vendored Core.

## Tài liệu chi tiết

- [Production installation và migration](docs/casan/CASAN_INSTALL_HYBRID.md)
- [Agentic client security boundary](docs/casan/CASAN_AGENTIC_CLIENT_SECURITY.md)
- [Windows client setup](docs/casan/CASAN_AGENTIC_CLIENTS_WINDOWS.md)
- [Packaging levels](docs/packaging/CASAN_PACKAGING_PLAN.md)
- [Production infrastructure](infra/production/README.md)

## License

Xem [LICENSE](LICENSE).