feat: add production Core runtime modes
This commit is contained in:
thanhnv
@@ -1,69 +1,92 @@
|
||||
# CASAN Prompt Enforcement for Adopted Projects
|
||||
|
||||
For the canonical agentic-coding guide installed into downstream repositories, see [`docs/casan/CASAN_PROMPT_ENFORCEMENT.md`](../casan/CASAN_PROMPT_ENFORCEMENT.md). For a full Windows installation starting from a repository with no CASAN files, see [`docs/casan/CASAN_ADOPTION_WINDOWS.md`](../casan/CASAN_ADOPTION_WINDOWS.md).
|
||||
CASAN adopts existing repositories through native project hooks. The global
|
||||
DevKit provides `casan init`; each project pins either a managed or vendored
|
||||
Core runtime.
|
||||
|
||||
The DevKit installer configures an adopted repository so supported repository agents and team members use CASAN as the certified prompt boundary.
|
||||
## Supported boundaries
|
||||
|
||||
## What is enforced
|
||||
- Claude Code: project hooks in `.claude/settings.json`.
|
||||
- Codex: project hooks in `.codex/hooks.json`, subject to explicit `/hooks`
|
||||
review and trust.
|
||||
- VS Code/Copilot: CASAN-owned explicit `@casan` route.
|
||||
|
||||
- `bin/casan-chat` is the macOS/Linux/WSL2 prompt entrypoint.
|
||||
- `bin/casan-chat.ps1` is the Windows wrapper and executes the same entrypoint through WSL2.
|
||||
- `.casan/prompt-policy.json` binds prompts and H6 telemetry to one `project_id`.
|
||||
- `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` tell supported repository agents to refuse direct prompt work and require resubmission through CASAN.
|
||||
- The standalone `.gitea/workflows/casan-prompt-enforcement.yml` workflow verifies that the policy, launchers, instructions, domain root, and workflow contract are present and have not been stripped. Existing project CI is not overwritten.
|
||||
- A certified prompt must produce a trace with passing H1-H7 gates and H6 telemetry attributed to the configured project.
|
||||
CASAN does not claim to intercept arbitrary prompts typed into external web
|
||||
sites or built-in Copilot Chat outside the explicit `@casan` route.
|
||||
|
||||
## Enforcement boundary
|
||||
## Install
|
||||
|
||||
A repository cannot technically intercept text typed directly into an external ChatGPT, Claude, or Copilot website. Such conversations are outside the CASAN runtime and therefore are **not CASAN-certified**. The enforceable rule is:
|
||||
|
||||
1. Use a CASAN-owned entrypoint for every project prompt.
|
||||
2. Repository-aware agents must refuse direct execution when their instruction file is loaded.
|
||||
3. Accept governed output only when its CASAN trace passes verification.
|
||||
|
||||
For stronger organizational control, restrict direct external AI sites at the identity, proxy, or network layer. That control is outside the repository and complements CASAN rather than replacing its H1-H7 evidence.
|
||||
|
||||
## Install or upgrade
|
||||
|
||||
From a checked-out CASAN Core repository:
|
||||
Install the DevKit once:
|
||||
|
||||
```bash
|
||||
packages/casan-devkit/install.sh \
|
||||
--target "/absolute/path/to/existing-project" \
|
||||
--project "project-id" \
|
||||
--domain "Project display name"
|
||||
sh install.sh --level devkit
|
||||
```
|
||||
|
||||
The installer is idempotent for the managed instruction blocks. Existing content outside the CASAN markers, project domain documents, project registry, and existing CI workflows is retained.
|
||||
|
||||
## Send prompts
|
||||
|
||||
macOS, Linux, or WSL2:
|
||||
Adopt an existing project with the recommended managed Core:
|
||||
|
||||
```bash
|
||||
bin/casan-chat "Review the current requirements and identify missing acceptance criteria"
|
||||
cd /absolute/path/to/existing-project
|
||||
casan init --project project-id --client claude,codex
|
||||
casan doctor
|
||||
casan verify-harness
|
||||
```
|
||||
|
||||
Windows PowerShell with WSL2:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File bin\casan-chat.ps1 "Review the current requirements"
|
||||
```
|
||||
|
||||
Run without a prompt to enter interactive mode.
|
||||
|
||||
## Verify
|
||||
|
||||
Verify the repository contract:
|
||||
For an offline/self-contained repository:
|
||||
|
||||
```bash
|
||||
bin/casan prompt verify
|
||||
casan init --runtime vendored --project project-id --client claude,codex
|
||||
```
|
||||
|
||||
Verify an individual governed result:
|
||||
Vendored Core is installed under `.casan/runtime/casan-core` using the same
|
||||
production allowlist as the global release. Tests, legacy `level5`, internal
|
||||
runners and Platform-only helpers are excluded.
|
||||
|
||||
## Runtime contract
|
||||
|
||||
`.casan/config.json` records:
|
||||
|
||||
- project ID and enforcement mode;
|
||||
- selected client integrations;
|
||||
- project capability level;
|
||||
- runtime mode and path.
|
||||
|
||||
`.casan/version.lock` records the exact Core version and integrity hash.
|
||||
`casan verify-harness` recomputes the live hash; it does not trust a cached
|
||||
value. Vendored mode fails closed if the local Core is absent instead of
|
||||
silently falling back to global Core.
|
||||
|
||||
## Existing repository safety
|
||||
|
||||
`casan init` merges only CASAN handlers into supported client configuration.
|
||||
Existing hooks, agents, skills, instructions and CI workflows are preserved.
|
||||
Re-running init is idempotent and preserves the selected runtime mode unless
|
||||
`--runtime managed|vendored` is explicitly supplied.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
bin/casan prompt trace <trace-id>
|
||||
casan doctor
|
||||
casan verify-harness
|
||||
casan level show
|
||||
```
|
||||
|
||||
Only the second command proves that the individual prompt completed H1-H7 and has matching H6 project telemetry.
|
||||
For Codex, open `/hooks`, review the exact project hook and trust its hash.
|
||||
|
||||
For CI, verify the pin before executing governance gates:
|
||||
|
||||
```bash
|
||||
casan verify-harness
|
||||
casan gate
|
||||
```
|
||||
|
||||
## Uninstall
|
||||
|
||||
```bash
|
||||
casan uninstall
|
||||
```
|
||||
|
||||
This removes CASAN hooks/config, CASAN-owned Gitea workflows, unchanged CASAN
|
||||
scaffold files and vendored Core. User-authored hooks/workflows and modified
|
||||
project files are retained. Add `--purge` to remove `.specify` logs/state, and
|
||||
use `--remove-vscode-extension` only when the shared extension is no longer
|
||||
needed by any project.
|
||||
|
||||
Reference in New Issue
Block a user