CASAN/README.md

# CASAN

CASAN là governance harness cho agentic coding. CASAN được cài một lần trên máy
developer, sau đó được liên kết vào từng repository bằng project hooks. CASAN
không thay thế IDE, coding agent hoặc workflow phát triển của project.

Project có thể tiếp tục dùng nguyên trạng slash commands, agents, skills, review
loops và cấu trúc source hiện hữu. CASAN không áp đặt một pipeline hoặc số bước
cố định.

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

| Thành phần | Trạng thái | Phạm vi |
|---|---|---|
| Core — Level 1 | Implemented | H1–H7 harness, hooks, policy gates, audit, evidence và CLI |
| DevKit — Level 2 | Implemented | Core + `casan init`, domain-pack và CI template |
| Platform — Level 3 | Preview | Control Panel được deploy riêng, không được cài vào project bằng `casan init` |
| Enterprise — Level 4 | Chưa phát hành | Installer chủ động từ chối |

Đối với repository đã có sẵn vỏ dự án, nên dùng **Level 1 cho project**. Chỉ
chọn Level 2 khi project thực sự cần domain-pack và CI template của CASAN.

## 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 CASAN một lần trên máy

Từ checkout hoặc release bundle của CASAN:

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

# Nếu launcher chưa nằm trên PATH
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
```

Gói global `devkit` được dùng vì nó chứa lệnh adoption `casan init`. Harness
được cài mặc định tại:

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

Bản cài là runtime allowlist tối giản: không mang theo test suites, internal CI
runners, thư mục legacy `level5`, Platform dashboard/local lab, source docs hay
release tooling. Source repository vẫn giữ tests để kiểm chứng chính CASAN.

### 2. Adopt vào repository hiện hữu

```bash
cd <project-root>

# Chỉ thêm governance config/hooks; không thêm domain-pack hoặc CI template
casan init --level core --client claude,codex --mode enforce

casan doctor
casan verify-harness
```

`casan init` có menu chọn client khi chạy tương tác. Trong automation nên chỉ
định rõ `--client`:

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

Với Codex, sau init phải mở `/hooks`, kiểm tra và trust đúng project hook hash.

### 3. Dùng project bình thường

Không cần gọi CASAN agent hoặc CASAN pipeline. Tiếp tục dùng workflow hiện hữu,
ví dụ `/bd:boss`, `/bd:generation`, `/bd:review`, hoặc chat bình thường không
chỉ định agent.

CASAN tự tham gia vào lifecycle của client đã enable:

1. `UserPromptSubmit`: admission và quét prompt.
2. `PreToolUse`: kiểm tra tool input và 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/Codex vẫn là model
executor duy nhất.

## Client support

| Client | Chat bình thường tự qua CASAN | Bước bắt buộc |
|---|---:|---|
| Claude Code CLI/extension | Có | Mở repository dưới dạng trusted project |
| Codex CLI/extension | Có | Mở `/hooks`, review và trust hook hash |
| GitHub Copilot Chat | Không | Cài CASAN VSIX và gửi `@casan <prompt>` |

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. Một 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"] --> C1["Claude Code"]
  U --> C2["Codex"]
  U --> C3["VS Code: @casan"]

  C1 --> E1["Project hook events"]
  C2 --> E1
  C3 --> E2["CASAN-owned VSIX route"]

  E1 --> B[".casan/casan-hook.py"]
  E2 --> B
  B --> V{"Global harness<br/>matches version.lock?"}
  V -- "No" --> D["Deny or degrade<br/>according to mode"]
  V -- "Yes" --> A["Client adapter"]
  A --> G["Agentic bridge"]

  subgraph TURN["Per-turn lifecycle"]
    direction LR
    L1["Admission<br/>H1 + H4"] --> L2["Pre-tool gate<br/>H2 + H4"]
    L2 --> L3["Post-tool evidence<br/>H5"]
    L3 --> L4["Finalize<br/>H3 + H5 + H6 + H7"]
  end

  G --> L1
  L4 --> S["Project runtime state<br/>.specify/logs + state"]
  L4 --> R["Native client result"]
```

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

CASAN dùng mô hình hybrid: policy code nằm ở global installation; project chỉ
giữ bootstrap, pin và state riêng.

```mermaid
flowchart TB
  subgraph M["Developer machine"]
    H["CASAN_HOME"]
    CUR["current<br/>symlink hoặc junction"]
    VER["versions/&lt;version&gt;"]
    CLI["bin/casan"]
    HAR["packages/casan-harness"]
    DEV["packages/casan-devkit"]

    H --> CUR --> VER
    H --> CLI
    VER --> HAR
    VER --> DEV
  end

  INIT["casan init"] --> CFG
  CLI --> INIT
  DEV --> INIT

  subgraph P["Existing project"]
    CFG[".casan/<br/>config.json<br/>version.lock<br/>agentic.env<br/>init-manifest.json"]
    BOOT[".casan/casan-hook.py"]
    STATE[".specify/<br/>logs/<br/>state/<br/>.gitignore"]
    CLIENTS["Client config khi được chọn<br/>.claude/settings.json<br/>.codex/hooks.json<br/>.vscode/extensions.json"]
    L2["Level 2 only<br/>.gitea/workflows/casan-ci.yml<br/>apps/&lt;project-id&gt;/domain/"]
    OWNED["Project-owned<br/>source, agents, skills,<br/>commands, hooks và CI khác"]
  end

  INIT --> BOOT
  INIT --> STATE
  INIT --> CLIENTS
  INIT -. "chỉ khi --level devkit" .-> L2
  INIT -. "không thay đổi" .-> OWNED
  CFG --> BOOT
  HAR -. "runtime policy" .-> BOOT
```

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

| Path | Hành vi |
|---|---|
| `.casan/config.json` | Lưu project id, mode và danh sách client |
| `.casan/version.lock` | Pin version và SHA-256 của global harness |
| `.casan/casan-hook.py` | Bootstrap stdlib, verify pin rồi dispatch adapter |
| `.casan/agentic.env` | Compatibility/reference flags; runtime đọc `config.json` |
| `.casan/init-manifest.json` | Ghi file đã tạo và backup |
| `.specify/logs`, `.specify/state` | Runtime trace, audit và state; 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 backup `<file>.casan-bak` cho file hiện
hữu. `init-manifest.json` ghi lại các file và backup liên quan.

### Nội dung luôn được giữ nguyê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 và JSON key không thuộc CASAN.
- CI/workflow hiện hữu.
- Vendored `packages/casan-harness` của project cũ; chỉ xóa sau khi đã migration
  toàn bộ CI và scripts sang global harness.

Nếu target chính là CASAN source hub, init từ chối để tránh self-adoption. Không
dùng `--force` trừ khi chủ động muốn kiểm thử trường hợp này.

## Chọn mode

| Mode | Dùng cho | Certification |
|---|---|---|
| `enforce` | Mặc định production | Side effect fail-closed; turn đủ evidence có thể certified |
| `observe` | Pilot và thu telemetry | Không chặn như production; luôn `observed_only` |

```bash
casan init --level core --client claude,codex --mode enforce
```

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`.

## Kiểm tra, cấu hình lại và nâng cấp

Kiểm tra project:

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

- Output mặc định được tối ưu để đọc trực tiếp trong terminal. Thêm `--json`
  sau command khi cần payload đầy đủ cho CI hoặc script, ví dụ
  `casan doctor --json`.
- `doctor`: kiểm tra config, bootstrap, hook schema, adapter smoke test, VSIX và
  cảnh báo trust.
- `verify-harness`: tính lại live hash và so với project pin; drift trả exit
  code `3`.
- `level show`: hiển thị package level đã cài và target level của project.

Đổi danh sách client bằng cách chạy lại init với **toàn bộ danh sách mong muốn**.
CASAN handler của client bị bỏ khỏi danh sách sẽ được gỡ, còn hook khác được giữ:

```bash
casan init --level core --client claude

# Tắt toàn bộ IDE integration của CASAN nhưng giữ config/state
casan init --level core --client none
```

`--client none` không uninstall VSIX đã cài trên máy; nếu không còn dùng route
`@casan`, gỡ extension `fpt-casan.casan-governed-chat` trong VS Code.

Gỡ CASAN khỏi project:

```bash
# Gỡ project hooks và config CASAN; giữ hook người dùng và runtime evidence
casan uninstall

# Đồng thời xóa .specify/logs và .specify/state
casan uninstall --purge

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

`uninstall` không tự xóa CI/domain template vì các file này có thể đã trở thành
source code của project, không tự xóa `.casan-bak`, và không mặc định gỡ VS Code
extension dùng chung cho các project khác.

Khi nâng cấp CASAN:

1. Chạy lại installer từ release đã duyệt.
2. Chạy lại `casan init` 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.

Trong production, không bỏ qua `HARNESS_INTEGRITY_DRIFT`.

## CI

Runner phải cài cùng release CASAN mà project đã pin. Gate tối thiểu:

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

Level 2 tạo `.gitea/workflows/casan-ci.yml` như một template nếu file chưa tồn
tại. Template phải được review theo runner và mô hình cài đặt 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.

## 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à tests |
| `packages/casan-devkit/` | Hybrid adoption, project bootstrap 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` |

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

- [Hybrid 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).