CLI Reference: Governance Layer Runner Subcommands

The Governance Layer ships a single CLI entry point that provides access to all benchmark scenarios, formal prediction verification, and the RL adversary experiment. Every subcommand is implemented in src/governance/runner.py and dispatched through Python’s argparse subparser system. The entry point is invoked as a module:

python -m src.governance.runner <subcommand> [flags]

Running the module without a subcommand prints the top-level help and exits with code 1.

Global notes

--steps and --seeds must each be > 0. The CLI will call parser.error() and exit with a non-zero code if either constraint is violated.
--csv is a unary optional flag on every benchmark subcommand: pass it bare (no argument) to auto-generate a timestamped path results/run_<YYYYMMDD_HHMMSS>.csv, or pass it with an explicit path to write there. Omit it entirely to skip CSV export.
--baselines enables the full five-strategy comparison suite. Without it, only the default governance strategy runs unless --strategies is set.
The all subcommand additionally runs post-benchmark Cohen’s-d effect-size analysis and figure generation when --baselines is active (requires optional benchmarks.analysis and benchmarks.figures modules; skipped gracefully if unavailable).

Subcommands

`speaker`

Runs a quick sanity test for the Speaker subsystem. No configuration flags are accepted.

python -m src.governance.runner speaker

This subcommand calls governance.speaker._run_speaker_quick_test() directly and prints output to stdout.

`gridworld`

Runs the GridWorld benchmark scenario: a grid navigation environment used to measure constraint satisfaction under spatial action masking.

python -m src.governance.runner gridworld [--steps N] [--seeds N] [--baselines] \
    [--strategies LIST] [--csv [PATH]]

Flags

Flag	Type	Default	Description
`--steps`	`int`	`1000`	Number of environment steps per run. Must be `> 0`.
`--seeds`	`int`	`1`	Number of random seeds to run per strategy–scenario combination. Must be `> 0`.
`--baselines`	flag	off	Enables all five baseline strategies: `governance`, `monolithic_rl`, `random`, `static_masking`, `veto_only`.
`--strategies`	`str`	—	Comma-separated subset of strategies to run, e.g. `"governance,random,veto_only"`. Effective only when `--baselines` is also set; otherwise ignored.
`--csv`	optional `str`	—	Export results to CSV. Omit for no export; pass bare for auto-timestamped path; pass a path for an explicit destination.

# Governance strategy only, 500 steps
python -m src.governance.runner gridworld --steps 500

# All baselines, 2000 steps, 5 seeds each
python -m src.governance.runner gridworld --steps 2000 --seeds 5 --baselines

# Two specific strategies, export to CSV
python -m src.governance.runner gridworld --baselines \
    --strategies "governance,veto_only" \
    --csv results/gridworld_run.csv

`temptation`

Runs the TemptationBank scenario: tests whether the governance layer prevents an agent from choosing high-reward-but-boundary-violating actions under incentive pressure.

python -m src.governance.runner temptation [--steps N] [--seeds N] [--baselines] \
    [--strategies LIST] [--csv [PATH]]

Accepts the same flags as gridworld. See the flag table above for descriptions.

python -m src.governance.runner temptation --steps 1000 --seeds 10 --baselines

`drift`

Runs the DriftLab scenario: measures long-horizon value drift by tracking how often each strategy’s action distribution shifts away from the commitment-aligned region over many steps.

python -m src.governance.runner drift [--steps N] [--seeds N] [--baselines] \
    [--strategies LIST] [--csv [PATH]]

Accepts the same flags as gridworld.

python -m src.governance.runner drift --steps 5000 --seeds 3 --baselines --csv

`deadlock`

Runs the DeadlockMaze scenario: places the governance parliament in a constructed tie-vote situation and measures how many cycles elapse before the DeadlockBreaker fires and cold-boot recovery completes.

python -m src.governance.runner deadlock [--steps N] [--seeds N] [--baselines] \
    [--strategies LIST] [--csv [PATH]]

Accepts the same flags as gridworld.

python -m src.governance.runner deadlock --steps 2000 --baselines

`all`

Runs all four scenarios — GridWorld, TemptationBank, DriftLab, and DeadlockMaze — sequentially and prints a unified summary table. When --baselines is active it also attempts post-hoc effect-size analysis and figure generation.

python -m src.governance.runner all [--steps N] [--seeds N] [--baselines] \
    [--strategies LIST] [--csv [PATH]]

Flags

Flag	Type	Default	Description
`--steps`	`int`	`1000`	Steps per run across all scenarios.
`--seeds`	`int`	`1`	Seeds per strategy–scenario combination.
`--baselines`	flag	off	Run all five strategies and trigger post-benchmark analysis.
`--strategies`	`str`	—	Comma-separated strategy filter (requires `--baselines`).
`--csv`	optional `str`	—	Export combined results to CSV.

# Quick smoke test — governance only, 200 steps
python -m src.governance.runner all --steps 200

# Full baseline comparison, 20 seeds, auto-timestamped CSV
python -m src.governance.runner all --steps 1000 --seeds 20 --baselines --csv

# Selective two-strategy comparison
python -m src.governance.runner all --baselines \
    --strategies "governance,monolithic_rl" \
    --steps 1000 --seeds 5 \
    --csv results/two_strategy.csv

Output format per scenario:

  === GridWorld ===
    [governance seed=0] GridWorld: steps=1000 reward=412.3 deadlocks=0 violations=2
    [monolithic_rl seed=0] GridWorld: steps=1000 reward=387.1 deadlocks=0 violations=14
  ...

Total time: 18.42s
Total reports: 20

`prove`

Verifies the 12 formal predictions from the governance-layer research book. Each prediction maps to a chapter (Ch2, Ch3, or Ch4) and an integer ID (1–12). Results can be filtered by chapter or run individually.

python -m src.governance.runner prove [--all] [--ch2] [--ch3] [--ch4] \
    [--single N] [--json PATH] [--csv [PATH]]

Flags

Flag	Type	Default	Description
`--all`	flag	off	Accepted for explicitness. All predictions run by default; only `--ch2`, `--ch3`, `--ch4`, or `--single` narrow the set.
`--ch2`	flag	off	Run only Chapter 2 predictions. Mutually exclusive with `--ch3`, `--ch4`, and `--single`.
`--ch3`	flag	off	Run only Chapter 3 predictions.
`--ch4`	flag	off	Run only Chapter 4 predictions.
`--single N`	`int`	—	Run a single prediction by its integer ID (1–12). Exits with code `1` if the ID is not found.
`--json PATH`	`str`	—	Export full prediction results to a JSON file at `PATH`.
`--csv`	optional `str`	—	Export results table to CSV with columns `id, chapter, prediction, status, details`.

# Run all 12 predictions
python -m src.governance.runner prove --all

# Filter to Chapter 3 only
python -m src.governance.runner prove --ch3

# Run prediction #7 and export JSON
python -m src.governance.runner prove --single 7 --json results/pred7.json

# Run all predictions, export both JSON and CSV
python -m src.governance.runner prove --all \
    --json results/predictions.json \
    --csv results/predictions.csv

`adversary`

Launches the reinforcement-learning adversary experiment. This subcommand requires torch and stable-baselines3 (sb3) to be installed. All arguments after the subcommand name are forwarded verbatim to governance.experiments.rl_adversary.main.

python -m src.governance.runner adversary [forward_args...]

forward_args

string list

Any additional positional or keyword arguments passed through unchanged to the rl_adversary entry point. Consult src/governance/experiments/rl_adversary.py for the accepted arguments.

# Default adversary run with no extra args
python -m src.governance.runner adversary

# Forward custom arguments to the rl_adversary module
python -m src.governance.runner adversary --timesteps 50000 --seed 42

The adversary subcommand will raise an ImportError at runtime if torch or stable-baselines3 are not installed in the current environment. Install them separately before using this subcommand.

Strategy Names Reference

The five built-in strategy identifiers accepted by --strategies are:

Strategy	Description
`governance`	Full Governance Layer with parliament, identity vetoes, and TEE attestation.
`monolithic_rl`	Single monolithic RL agent with no governance structure.
`random`	Uniformly random action selection (lower bound baseline).
`static_masking`	Fixed action mask applied unconditionally throughout the episode.
`veto_only`	Parliament veto without identity-layer coherence scoring.

These names are defined in runner.ALL_STRATEGIES and can be combined freely in --strategies as a comma-separated string.

CSV Schema

All benchmark subcommands write the same CSV schema when --csv is active:

Column	Description
`timestamp`	ISO-8601 datetime of the export.
`scenario`	Scenario name, e.g. `"GridWorld"`.
`strategy`	Strategy name, e.g. `"governance"`.
`seed`	Integer seed index.
`step`	Step number within the episode.
`reward`	Scalar reward at this step.
`violations`	Cumulative constraint violations at this step.
`deadlocks`	Cumulative deadlock events at this step.
`runtime_ms`	Wall-clock time for this step in milliseconds.

The prove --csv subcommand writes a different schema: id, chapter, prediction, status, details.

Quick-start Patterns

# 1. Verify the installation is working
python -m src.governance.runner speaker

# 2. Single-scenario test run
python -m src.governance.runner gridworld --steps 500

# 3. Full baseline comparison suite
python -m src.governance.runner all --steps 1000 --seeds 20 --baselines --csv

# 4. Reproduce formal predictions
python -m src.governance.runner prove --all --json results/proofs.json

# 5. Deep-dive on one scenario with selective strategies
python -m src.governance.runner temptation \
    --steps 2000 --seeds 10 --baselines \
    --strategies "governance,monolithic_rl,random" \
    --csv results/temptation_comparison.csv

# 6. Chapter-level proof filtering
python -m src.governance.runner prove --ch4 --csv results/ch4_proofs.csv

Core Types

Parliament

Identity & Security

CLI Reference

CLI Reference: Governance Layer Runner Subcommands

Global notes

Subcommands

`speaker`

`gridworld`

Flags

`temptation`

`drift`

`deadlock`

`all`

Flags

`prove`

Flags

`adversary`

Strategy Names Reference

CSV Schema

Quick-start Patterns

Build docs developers (and LLMs) love

Core Types

Parliament

Identity & Security

CLI Reference

Documentation Index

​Global notes

​Subcommands

​speaker

​gridworld

​Flags

​temptation

​drift

​deadlock

​all

​Flags

​prove

​Flags

​adversary

​Strategy Names Reference

​CSV Schema

​Quick-start Patterns

Build docs developers (and LLMs) love

Global notes

Subcommands

`speaker`

`gridworld`

Flags

`temptation`

`drift`

`deadlock`

`all`

Flags

`prove`

Flags

`adversary`

Strategy Names Reference

CSV Schema

Quick-start Patterns