gitea-admin/CASAN
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add production Core runtime modes

Browse Source
This commit is contained in:
thanhnv
2026-07-24 12:16:11 +07:00
parent e359989a74
commit eb3525456f
13 changed files with 659 additions and 397 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/packaging/ADOPTION_GUIDE.md
+38 -30
View File
@@ -1,33 +1,45 @@
# CASAN Adoption Guide
The installer also provisions the mandatory prompt-enforcement pack. After adoption, send project prompts through `bin/casan-chat` (or `bin/casan-chat.ps1` on Windows/WSL2) and run `bin/casan prompt verify`. The canonical from-scratch guides are [CASAN_ADOPTION_WINDOWS.md](../casan/CASAN_ADOPTION_WINDOWS.md) and [CASAN_PROMPT_ENFORCEMENT.md](../casan/CASAN_PROMPT_ENFORCEMENT.md); the installer renders both into the target repository.
CASAN separates machine installation from project adoption. Install the DevKit
once so the `casan` command is available, then enroll each repository with a
version/hash lock. Application teams never edit gate logic (H1→H7).
How a downstream project adopts the CASAN governance harness. Adoption is **config +
domain only** — you never edit gate logic (H1→H7).
## Option A — Managed Core (recommended)
## Option A — DevKit install (recommended)
Clone CASAN Core from your Gitea repository once, and pull the latest `main` before each install or upgrade:
Install from an approved checkout or release:
```bash
git clone <gitea-casan-core-url> casan-core
cd casan-core
git pull --ff-only origin main
sh install.sh --level devkit
cd /path/to/my-project
casan init --project ticketing --client claude,codex
casan doctor
casan verify-harness
```
Then run the installer from that CASAN checkout:
The project defaults to Level 1/Core with runtime mode `managed`. Core remains
under `$CASAN_HOME`; the repository receives `.casan` config/lock/bootstrap and
the selected client hooks. The CLI output states the resolved runtime path.
Use this for developer workstations and managed CI runners. CI must install the
same release recorded by `.casan/version.lock` before running gates.
## Option B — Vendored Core (offline/self-contained)
```bash
packages/casan-devkit/install.sh --target ../my-project --project ticketing --domain "Ticketing"
cd /path/to/my-project
casan init --runtime vendored --project ticketing --client claude,codex
casan doctor
casan verify-harness
```
This copies the core harness + `bin/casan` into `../my-project`, scaffolds
`apps/ticketing/domain/` from the domain-pack template, installs the prompt entrypoints and
standalone `.gitea/workflows/casan-prompt-enforcement.yml`, and registers the project in
`project-registry.json`. Existing domain files, registry state, and project CI are preserved.
The copied harness follows the production allowlist and excludes CASAN's own tests,
legacy `level5/`, internal CI runners, and Platform-only helpers.
## Option A2 — New production project shell
This installs the production-only Core at
`.casan/runtime/casan-core/`, including a local `bin/casan`. It excludes tests,
legacy `level5`, internal runners and Platform helpers. Choose this for
air-gapped customers or repositories that must execute without a machine-level
runtime. Re-running init preserves the selected mode; switching mode requires
an explicit `--runtime managed|vendored`.
## Option C — New production project shell
```bash
packages/casan-devkit/install.sh \
@@ -41,16 +53,10 @@ This creates a strict-TypeScript NestJS/React monorepo, health bootstrap, tests,
images, GitHub CI, a complete Domain Pack, versioned quality profile, project manifest, CASAN CLI,
harness, and manifest-driven pipeline. Existing different files are never overwritten.
## Option B — Core tarball (harness-only / CI gate)
```bash
tar -xzf casan-core-v1.0.0.tar.gz
cp -R casan-core-v1.0.0/{packages,bin,VERSION} /path/to/project/
```
Then create `apps/<project>/domain/` yourself (see `DOMAIN_PACK_GUIDE.md`).
This harness-only option does not install the mandatory repository prompt-enforcement pack;
use Option A when every project prompt must be governed and certifiable.
The legacy direct installer is reserved for generating a new application shell;
do not use it merely to enroll an existing repository.
## Option C — Docker (no install into repo)
## Option D — Docker (no install into repo)
```bash
docker run --rm -v "$PWD":/workspace -w /workspace casan-harness:1.0.0 casan gate
```
@@ -77,11 +83,13 @@ bin/casan pipeline --manifest apps/<project>/domain/project.manifest.json
```
## Path model (what lives where)
- **Harness code** → `packages/casan-harness/` (never edited by adopters).
- **Managed Core** → `$CASAN_HOME/current/packages/casan-harness/`.
- **Vendored Core** → `.casan/runtime/casan-core/packages/casan-harness/`.
- **Project lock/config** → `.casan/config.json` and `.casan/version.lock`.
- **Your domain data** → `apps/<project>/domain/` (via `CASAN_DOMAIN_ROOT`).
- **Runtime state** → `.specify/` (logs, audit, governance — created on first run).
Paths resolve via `packages/casan-harness/scripts/bash/casan-paths.sh` (marker walk-up:
`.specify` or `packages/casan-harness`), so a freshly-extracted bundle works immediately.
The bootstrap resolves the mode/path from the project lock and verifies the live
Core hash before dispatch.
## Proving reuse
Two+ projects sharing the same harness package/version → `bin/casan reuse` prints
docs/packaging/PROMPT_ENFORCEMENT_GUIDE.md
+69 -46
View File
@@ -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.