gitea-admin/CASAN
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
34a6b013c09f96397bf12ae818cd9869b438a430
CASAN/README.md
T

20 KiB
Raw Blame History

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 level + 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 — Level 1 Implemented H1–H7 harness, hooks, policy gates, audit, evidence và CLI
DevKit — Level 2 Implemented Core + adoption tooling, domain-pack và CI template
Platform — Level 3 Preview Control Panel deploy riêng; casan init chỉ áp dụng nền Level 2
Enterprise — Level 4 Chưa phát hành CLI chủ động từ chối, không giả lập tính năng

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
Capability của project --level core, devkit, platform core
Vị trí Core runtime --runtime managed, vendored managed
Cách thực thi policy --mode enforce, observe enforce

--level core không có nghĩa Core phải nằm trong repository. Level mô tả capability; runtime mô tả vị trí. Đây là hai quyết định độc lập.

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:

# 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, level, 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 verify-harness
casan level 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:

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

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
│   ├── 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:

# 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

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

Reference in New Issue View Git Blame Copy Permalink