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.

Ngay sau init, CASAN ghi hai projection do CASAN sở hữu: .casan/discovery.json và .casan/readiness.json. Readiness tách ba chiều: Core, Domain Pipeline và Provider Telemetry. Core có thể sẵn sàng cho prompt/report dù hai chiều tùy chọn còn not_configured hoặc optional_unavailable.

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.

# Sau một prompt
casan report latest
casan readiness --refresh              # Core / Domain / Provider, không chạy pipeline
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.

Native plugin façade — tùy chọn

Repository root đồng thời là marketplace source cho Codex và Claude Code. Plugin chỉ cung cấp skill $casan để agent biết cách adopt, diagnose và verify CASAN; nó không tự bật hook, không tự cài runtime và không thay thế bước trust của client.

Từ một checkout đã được tổ chức phê duyệt:

# Codex
codex plugin marketplace add /absolute/path/to/CASAN
codex plugin add casan@casan

Trong Claude Code:

/plugin marketplace add /absolute/path/to/CASAN
/plugin install casan@casan

Sau khi cài plugin, mở session mới và gọi $casan. Runtime production vẫn được cài một lần bằng install.sh/install.ps1, sau đó mỗi repository phải chạy casan init. Không cài chồng native plugin và một bản skill copy thủ công vào cùng client.

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

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

# 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

# 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

cd <project-root>
casan init

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

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

casan doctor
casan readiness --refresh
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.

casan readiness là product status dành cho người vận hành và dashboard; casan doctor là diagnostic sâu cho integrity, hook, smoke test và trust. Không dùng trạng thái thiếu Domain Pack hoặc thiếu token/cost provider để hạ Core thành failed.

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:

UserPromptSubmit: admission và quét prompt.
PreToolUse: kiểm tra tool input, chặn side effect không hợp lệ.
PostToolUse: ghi evidence của tool result.
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:

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:

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.

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.

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

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`

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:

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

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

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`

<project>/
├── .casan/
│   ├── config.json
│   ├── version.lock
│   ├── casan-hook.py
│   ├── agentic.env
│   ├── discovery.json
│   ├── readiness.json
│   ├── domain.json              # chỉ khi chọn manifest bằng casan domain configure
│   ├── 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/discovery.json`	Inventory bounded các marker/source/requirements/Domain Pack candidate; không sửa source
`.casan/readiness.json`	Contract Core / Domain Pipeline / Provider Telemetry dùng chung cho CLI và viewer
`.casan/domain.json`	Reference CASAN-owned tới manifest do project sở hữu; chỉ tạo khi `casan domain configure`
`.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:

# 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

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

Vendored

Cài hoặc giải nén DevKit release đã duyệt trên máy thực hiện upgrade.
Chạy casan init --runtime vendored; CASAN refresh Core production-only trong project.
Review thay đổi runtime, chạy doctor và verify-harness.
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

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

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:

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
`.codex-plugin/`, `.claude-plugin/`	Native marketplace manifests; không tự bật enforcement
`skills/casan/`	Operator skill façade dùng chung cho Codex và Claude Code
`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

License

Xem LICENSE.

24 KiB Raw Permalink Blame History Unescape Escape

CASAN