103 lines
4.2 KiB
Markdown
103 lines
4.2 KiB
Markdown
# CASAN Adoption Guide
|
|
|
|
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).
|
|
|
|
## Option A — Managed Core (recommended)
|
|
|
|
Install from an approved checkout or release:
|
|
|
|
```bash
|
|
sh install.sh --level devkit
|
|
cd /path/to/my-project
|
|
casan init --project ticketing --client claude,codex
|
|
casan doctor
|
|
casan verify-harness
|
|
```
|
|
|
|
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
|
|
cd /path/to/my-project
|
|
casan init --runtime vendored --project ticketing --client claude,codex
|
|
casan doctor
|
|
casan verify-harness
|
|
```
|
|
|
|
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 \
|
|
--target ../my-project \
|
|
--project ticketing \
|
|
--domain "Ticketing" \
|
|
--template nestjs-react
|
|
```
|
|
|
|
This creates a strict-TypeScript NestJS/React monorepo, health bootstrap, tests, Docker multi-stage
|
|
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.
|
|
|
|
The legacy direct installer is reserved for generating a new application shell;
|
|
do not use it merely to enroll an existing repository.
|
|
|
|
## Option D — Docker (no install into repo)
|
|
```bash
|
|
docker run --rm -v "$PWD":/workspace -w /workspace casan-harness:1.0.0 casan gate
|
|
```
|
|
See `DOCKER_GUIDE.md`.
|
|
This runtime-only option also does not enforce repository-agent entrypoints.
|
|
|
|
## After install
|
|
1. Requirement → `apps/<project>/domain/input/requirement.md` (keep the `| FR-xx |` table).
|
|
2. Golden baseline → `apps/<project>/domain/golden-runs/<artifact>.golden.txt`.
|
|
3. Corpus → `apps/<project>/domain/corpus/` (redteam + benign) for H4 scoring.
|
|
4. Requirement→code→test map → `apps/<project>/domain/traceability-map.json`.
|
|
5. Run:
|
|
```bash
|
|
CASAN_DOMAIN_ROOT=apps/<project>/domain bin/casan gate # full governance gate
|
|
bin/casan run in.txt out.txt my_step -- <command> # one governed step
|
|
bin/casan reuse # HARNESS_REUSE_VALID
|
|
```
|
|
|
|
For a manifest-enabled project prefer:
|
|
|
|
```bash
|
|
bin/casan project validate --manifest apps/<project>/domain/project.manifest.json
|
|
bin/casan pipeline --manifest apps/<project>/domain/project.manifest.json
|
|
```
|
|
|
|
## Path model (what lives where)
|
|
- **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).
|
|
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
|
|
`HARNESS_REUSE_VALID ... project_count=N`. This is the evidence that the harness is genuinely
|
|
reusable, not copy-pasted. See `docs/plans/CASAN_PLAN_06_ONBOARD.md`.
|
|
|
|
## Upgrading
|
|
Re-run `install.sh` from a newer DevKit (or re-extract a newer core tarball). Your
|
|
`apps/<project>/domain/` and `.specify/` state are untouched — only `packages/casan-harness/`
|
|
+ `bin/casan` are replaced. Keep `harness_version` aligned across projects for reuse to count.
|