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:

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)

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

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)

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

Requirement → apps/<project>/domain/input/requirement.md (keep the | FR-xx | table).
Golden baseline → apps/<project>/domain/golden-runs/<artifact>.golden.txt.
Corpus → apps/<project>/domain/corpus/ (redteam + benign) for H4 scoring.
Requirement→code→test map → apps/<project>/domain/traceability-map.json.

Run:

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:

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.

4.2 KiB Raw Blame History