CLI — pnpm forge

The whole rig lifecycle is driven through one neutral dispatcher:

pnpm forge <verb> <use-case>[:<stack>] [task-args…]

The verb is the stable, use-case-agnostic vocabulary; the use-case is a parameter. Nothing at the engine or repo-root layer names a specific use-case — adding one is mkdir use-cases/<name>/…, with no new script.

Why a dispatcher, not bare pnpm <verb>

pnpm up aliases pnpm update, pnpm setup configures pnpm itself, and pnpm run is reserved — bare verb scripts get hijacked. go-task’s includes: would give task booklogr:setup, which is use-case-first again. The forge shim sits above go-task and gives a neutral, verb-first surface; go-task still does the actual lifecycle work per the stack’s Taskfile.yml.

Phase verbs

Each phase verb maps to a task in the stack’s Taskfile.yml:

Verb	Purpose	Accepts SCENARIO_ID
setup	One-time substrate import + scaffolding	No
up	Bring up the deployment + observability stack	No
quiesce	Quiesce the observability plane before arm (#74); scoped to the scenario’s [verify] services and exempts role: ambient alerts, tune with QUIESCE_DEADLINE_S	Yes
arm	Inject the fault and confirm the target alert fires	Yes
agent	Bring up the sealed agent sandbox	No
mcp	Start the optional read-only Grafana MCP telemetry seam	No
auto	Automated incident cycle: alert push → agent → grade (ADR-0025); runs runner pre-flight check (confirm-runner.mjs), aborts with exit code 86 if runner is missing/unregistered	Yes
run	Drive a graded run (scripted, or RUNNER=external, id=<run-id>); runs runner pre-flight check	Yes
verify	Behavioural verification + boundary / de-tell probes	No
down	Tear down the deploy + load planes	No
status	Fast per-plane runtime view (forge plane, deploy N/M with offenders named, agent workspace, alert state, p99)	No
doctor	Preflight misconfiguration + bootstrap checks, all planes, per-line PASS/FAIL/WARN with fix hints, exit non-zero on any FAIL	No
console	Harness-side operator console (status + deep-links)	No
smoke	Quick positive/negative smoke checks	Yes

Cross-use-case verbs

Verb	Purpose
dashboard	Spawns the cross-use-case operator control plane (tools/dashboard, ADR-0024)
forge-up / forge-down	forge-plane gitea+runner lifecycle; forge-up recovers a stale runner and never restarts a healthy gitea

Composite verbs

Composites expand to an ordered sequence of phase verbs:

Composite	Expands to	Accepts SCENARIO_ID
fresh	setup → up	No
agent-up	arm → agent	Yes
incident	arm → run → verify	Yes
e2e	setup → up → arm → run → verify → down	Yes

Arguments

Trailing task args are passed through to the underlying task. Inside a composite, they flow to each scenario-aware phase (arm, run, auto, smoke); other phases receive none. For example, agent-up forwards SCENARIO_ID=<id> to its arm phase.

Scenario-aware verbs (arm, auto, run, smoke, agent-up, incident, e2e) accept SCENARIO_ID specified either via environment variable (SCENARIO_ID=<id>) or trailing task argument (SCENARIO_ID=<id>). If omitted, it defaults to latency-cache-stampede. Any other verb invoked with SCENARIO_ID fails loudly. Scenario IDs must be valid lowercase slugs matching /^[a-z0-9][a-z0-9-]*$/; invalid slugs are rejected before task execution.

The run and auto verbs accept id=<run-id> to pin the banked run record ID.

pnpm forge up booklogr                      # single phase
pnpm forge run booklogr RUNNER=external id=r1   # args → the run task
pnpm forge auto booklogr id=r1              # automated cycle with pinned run ID
pnpm forge incident booklogr                # composite: arm → run → verify
pnpm forge smoke booklogr SCENARIO_ID=cascading-upstream-failure

Stack resolution

<use-case>[:<stack>] resolves to a stack directory under use-cases/<name>/stacks/:

• If the use-case has exactly one stack, you can omit :<stack>.
• If it has more than one, you must address one explicitly as name:stack, otherwise the dispatcher errors and lists the available stacks.

Listing phases

pnpm forge menu booklogr     # alias: list — runs `task --list` for the stack

Related repo-root scripts

These are plain Node scripts (no install needed) used during substrate intake:

Script	What it does
pnpm guard	Contamination-guard: scan a target for harness leakage + marker comments
pnpm guard:strict	The strict variant
pnpm detell	De-tell judge: score a target for “is this a rig?” tells
pnpm detell:grade	The grading variant
pnpm certify:hash	Computes the ADR-0026 own_hash and shared_hash for a scenario
pnpm certify:validate	Validates acceptance manifests against their versioned schema
pnpm rules-lint	Lints Prometheus alert rules under observability/rules/*.yml for mandatory service labels
pnpm test:*	Runs suite-specific tests (e.g., test:certify, test:rules-lint, test:core)
node tools/record/migrate-run-records.mjs	Migrates older run records to the canonical snake_case run-record.v1 schema
node tools/transcript/write-handoff.mjs	Driver contract script to hand off agent transcript/RCA to the engine

See also

• Run an incident — verbs mapped to lifecycle phases.