116 lines
4.6 KiB
Markdown
116 lines
4.6 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.
|
||
|
||
After any prompt, visual assurance is available from Core itself:
|
||
|
||
```bash
|
||
casan report latest
|
||
casan view
|
||
```
|
||
|
||
The viewer is single-project, offline-capable and read-only. It starts lazily on
|
||
`127.0.0.1`, so projects do not need Platform, Node/npm or an always-running
|
||
service merely to inspect H1–H7 and H6.
|
||
|
||
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).
|
||
- **Local viewer state** → `.specify/state/local-viewer.json` (`0600` on POSIX,
|
||
project ACL on Windows; ephemeral loopback port/session token; removed on stop).
|
||
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.
|