CASAN/docs/packaging/ADOPTION_GUIDE.md

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. See PROMPT_ENFORCEMENT_GUIDE.md for the technical boundary and per-trace certification.

How a downstream project adopts the CASAN governance harness. Adoption is config + domain only — you never edit gate logic (H1→H7).

Option A — DevKit install (recommended)

Clone CASAN Core from your Gitea repository once, and pull the latest main before each install or upgrade:

git clone <gitea-casan-core-url> casan-core
cd casan-core
git pull --ff-only origin main

Then run the installer from that CASAN checkout:

packages/casan-devkit/install.sh --target ../my-project --project ticketing --domain "Ticketing"

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.

Option A2 — 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.

Option B — Core tarball (harness-only / CI gate)

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.

Option C — 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)

• Harness code → packages/casan-harness/ (never edited by adopters).
• 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.

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.