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:

# 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

# 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

CASAN tách rõ hai quyết định:

Phạm vi	Ý nghĩa
--level core (mặc định)	Capability áp dụng cho project: governance Core, không thêm domain-pack/CI
--runtime managed (mặc định project mới)	Dùng Core global đã pin version/hash; repo nhẹ, nâng cấp tập trung
--runtime vendored	Copy Core production-only vào .casan/runtime/casan-core; phù hợp offline/air-gapped/self-contained

cd <project-root>

# Production mặc định: managed Core
casan init --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. Project hiện hữu mặc định dùng Level 1 (core); chỉ truyền --level devkit khi muốn CASAN bổ sung CI template và domain-pack:

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
casan init --level devkit --client claude,codex

# Project phải tự chứa Core (offline/air-gapped)
casan init --runtime vendored --client claude,codex

Output init và casan level show luôn hiển thị runtime mode cùng đường dẫn thực tế. Chạy lại init giữ mode hiện tại; chỉ đổi khi truyền rõ --runtime managed hoặc --runtime vendored.

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

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 mặc định dùng managed runtime: policy code nằm ở global installation, project giữ bootstrap, pin và state riêng. Với --runtime vendored, cùng Core production-only được đặt tại .casan/runtime/casan-core.

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

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:

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

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:

# 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 xóa workflow CASAN trong .gitea, xóa các scaffold file CASAN còn nguyên checksum và tự dọn thư mục cha khi đã rỗng. Workflow/file của project, scaffold file đã chỉnh sửa và .casan-bak được giữ lại để tránh mất dữ liệu. Vendored Core trong .casan/runtime/casan-core cũng được xóa. Lệnh 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:

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
• Agentic client security boundary
• Windows client setup
• Packaging levels
• Production infrastructure

License

Xem LICENSE.