CASAN/docs/packaging/ADOPTION_GUIDE.md

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 readiness --refresh
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:

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.

The dashboard and CLI expose three independent states:

• Core: installation acceptance and client activation;
• Domain Pipeline: optional project-specific SRS→test configuration;
• Provider Telemetry: optional model/provider token and cost coverage.

not_configured Domain Pipeline and optional_unavailable Provider Telemetry do not block Core. casan report export is on-demand and must not run after every prompt.

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

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:

   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).
• 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.