cents experiment

Spec fields

The YAML spec passed to register declares the hypothesis and the verdict-readiness criteria. Every field except name, hypothesis, and primary_metric has a default.

Field	Default	What it does
name	—	Unique experiment name, used as a foreign key on every thesis opened while active.
hypothesis	—	Free-text rationale, frozen at register time.
primary_metric	—	The metric finalize will read the verdict against.
minimum_n_per_arm	100	Per-arm closed-thesis count before verdict_ready flips true.
minimum_calendar_days	14	Calendar-day floor from registration before verdict_ready flips true. Pilots can run lower (30 days for a 30-day pilot); full runs run higher (90 for a 90-day forward test). Combined with minimum_n_per_arm under a “later of” stopping rule, so neither gate short-circuits the other.
stopping_rule	later_of	How to combine the N and calendar gates.

The two pre-registered specs shipped in the repo are:

• experiments/pilot_v1.yaml — 30-day pilot, minimum_n_per_arm: 200, minimum_calendar_days: 30, ~$10/day cost target. Coarse by design; the goal is operational shakedown plus a go/no-go directional read.
• experiments/hit_rate_delta_v1.yaml — 90-day full run, minimum_n_per_arm: 400, minimum_calendar_days: 90, ~$15/day cost target. Powers ~10pp gap detection at 80% power / α=0.05. Spec preamble explicitly says do not register until the pilot lands a positive directional read.

Register and inspect pre-registered research experiments.

Synopsis

cents experiment <subcommand> [OPTIONS] [ARGS]...

Subcommands

• cents experiment finalize — Finalize an experiment (lock its status and optionally record a verdict).
• cents experiment list — List registered experiments.
• cents experiment register — Register a new experiment, freezing the current factory.toml SHA.
• cents experiment status — Show progress of an active experiment against its targets.

cents experiment finalize

Finalize an experiment (lock its status and optionally record a verdict).

Blocks by default when the experiment is not verdict-ready (insufficient N per arm, too-recent registration, or factory.toml SHA drift). Pass --force to override; the verdict will be tagged forced: true.

Synopsis

cents experiment finalize [OPTIONS] NAME

Arguments

Argument	Type	Required
NAME	text	yes

Options

Option	Type	Default	Description
--verdict PATH	path		JSON file with the verdict on the primary metric.
--force	boolean	false	Bypass the verdict-ready check and finalize early. The recorded verdict will be tagged with ‘forced’: true so downstream analytics can flag the cohort as below-discipline.
`—output/-o [text	json]`	[text | json]

Example

cents experiment finalize [OPTIONS] NAME

cents experiment list

List registered experiments.

Synopsis

cents experiment list [OPTIONS]

Options

Option	Type	Default	Description
`—output/-o [text	json]`	[text | json]

Example

cents experiment list [OPTIONS]

cents experiment register

Register a new experiment, freezing the current factory.toml SHA.

Synopsis

cents experiment register [OPTIONS] SPEC_PATH

Arguments

Argument	Type	Required
SPEC_PATH	path	yes

Options

Option	Type	Default	Description
`—output/-o [text	json]`	[text | json]

Example

cents experiment register [OPTIONS] SPEC_PATH

cents experiment status

Show progress of an active experiment against its targets.

NAME may be passed positionally OR via —name; both forms are equivalent. Defaults to the active experiment when omitted.

Synopsis

cents experiment status [OPTIONS] [NAME_ARG]

Arguments

Argument	Type	Required
NAME_ARG	text	no

Options

Option	Type	Default	Description
--name TEXT	text		Experiment name (defaults to the active one)
`—output/-o [text	json]`	[text | json]

Example

cents experiment status [OPTIONS] [NAME_ARG]