crucihil author

Synopsis

crucihil author <source> [options]

Description

crucihil author is the self-verifying authoring loop: point it at a firmware component’s source and get a test suite that is proven to catch regressions, not just one that passes.

analyze (contract) → generate → baseline gate → [--verify: mutate → repair] → write

Analyze — extracts the component’s signal contract (with evidence chains) from the source, the DBC corpus, and — with --repo — the cross-component port graph.
Generate — an AI generates a suite from the contract; a deterministic static generator is the guaranteed fallback.
Baseline gate — every candidate must compile, import, load as a manifest, and run green on the rig before it is accepted. Failures feed back into AI repair rounds.
Verify (with --verify) — the suite is mutation-verified and weak tests are regenerated from the mutation evidence, ending with the strength matrix.
Write — the promoted suite lands in --output-dir after a confirmation prompt (skipped with --yes).

Broken AI output never reaches disk. Every candidate must pass the compile → import → manifest-load → green-baseline-run gate; after the AI repair rounds are exhausted, the deterministic static generator takes over — and it must itself pass the gate before anything is written.

Options

path

required

Component source file or directory to author tests for. With --protocol, this is a protocol description instead (C packet header, protobuf, or prose spec).

string

Component name. Defaults to the source directory name. Short form: -c.

path

default:"rigs/virtual.toml"

Rig TOML the baseline gate runs against (virtual rig by default). Short form: -r.

path

DBC file for the signal corpus. Repeatable.

path

Firmware repo root — enables cross-component port-graph resolution for the contract.

path

Dependency path (shim headers etc.), parsed alongside the primary source. Repeatable.

path

default:"tests/suites"

Directory the promoted suite (YAML + Python) is written to.

string

Suite name. Default: <component>_contract.

string

default:"crucihil"

Output format: crucihil (native YAML + Python), pytest (test_*.py + wrapper manifest), or robot (.robot suite + wrapper manifest). See Framework output.

string

AI provider: anthropic, openai, or gemini. If omitted, auto-detected from environment variables. Short form: -p.

integer

default:"2"

Max AI repair rounds before the static fallback takes over.

boolean

default:"false"

Skip the write confirmation prompt. Short form: -y.

boolean

default:"false"

After authoring: mutation-verify the suite, regenerate weak tests from the mutation evidence, and end with the strength matrix — the full self-verifying loop.

integer

default:"3"

Repair-loop cap for --verify: verify → regenerate → re-verify rounds.

boolean

default:"false"

Treat source as a protocol description: generate a declarative wire-format YAML instead of tests. See Protocol import mode.

path

Output path for --protocol. Default: <protocol>.yaml in the current directory.

Exit codes

Code	Meaning
`0`	Suite authored, gated, and written
`2`	Pipeline failure — analysis error, every candidate (including the static fallback) failed the baseline gate, protocol import failed the round-trip harness, or the write was declined

Output format

Component : BrakeController
Rig       : rigs/virtual.toml
Analyzing component (contract extraction)...
Generating + gating suite on the rig (may take a minute)...

  Suite     : tests/suites/brakecontroller_contract.yaml
  Tests     : tests/suites/brakecontroller_contract.py  (5 functions)
  Contract  : contracts/BrakeController.json
  Generator : ai
  Baseline  : 5/5 passed on rigs/virtual.toml

  Run it:   crucihil run --suite tests/suites/brakecontroller_contract.yaml --rig rigs/virtual.toml

If any tests came from low-confidence signal matches, a ⚠ Review line lists them. If AI attempts failed the gate before one succeeded, a Repairs line reports how many.

Framework output

With --framework pytest or --framework robot, the baseline gate runs through the framework executors instead of the native runner, and the promoted output is a native test file plus a wrapper manifest:

pytest → test_<suite>.py + <suite>.yaml
robot → <suite>.robot + <suite>.yaml

The wrapper manifest points crucihil run at the foreign file via the framework: and path: fields:

suite:
  name: brakecontroller_contract
  version: "1.0.0"
  description: "Contract tests for BrakeController"

framework: pytest
path: tests/suites/test_brakecontroller_contract.py

tests: []

The result is runnable via crucihil run like any other suite, and verifiable via crucihil verify.

With --verify --framework pytest|robot you get the strength report, but the evidence-driven auto-repair loop regenerates native suites only — weaknesses in foreign-format output are reported for manual review.

The `--verify` loop

--verify chains mutation verification onto the authored suite: baseline run + one run per mutation (dead DUT, stuck outputs, latency violations, declared faults), then regenerates any test that missed a mutation, up to --max-iterations rounds. The command ends with the tests × mutations strength matrix:

  ✓ Every planned mutation is caught — the suite is verified.

or, if the iteration cap is reached with weaknesses remaining:

  ⚠ 2 residual weakness(es) remain after the iteration cap — review these tests by hand.

See crucihil verify for the mutation kinds, outcomes, and report format.

Protocol import mode

With --protocol, source is a protocol description — a C packet header, a protobuf definition, or a prose spec — and the output is a declarative wire-format YAML, not tests. The AI writes the spec, never code, and the spec must pass the round-trip verification harness (encode → decode → compare) before it is written. Failed attempts are repaired up to --repair-rounds times.

crucihil author protocol_header.h --protocol

Importing protocol from protocol_header.h...
Generating spec + round-trip verification (may repair)...

  Spec      : telemetry.yaml  (harness-verified)
  Protocol  : telemetry
  Messages  : StatusReport, SensorFrame  (12 signals)

  Wire it into a rig:
    [rig.custom.telemetry]
    backend     = "virtual_datagram"
    definitions = "telemetry.yaml"

Examples

Author a suite for one component (virtual rig gates the output)

crucihil author src/brake_controller/ -c BrakeController --dbc defs/vehicle.dbc

The full loop: author + mutation-verify + regenerate weak tests

crucihil author src/brake_controller/ -c BrakeController --repo firmware/ --verify -y

Emit the suite in your team’s own framework

crucihil author src/brake_controller/ -c BrakeController --framework pytest
crucihil author src/brake_controller/ -c BrakeController --framework robot

Import a custom protocol spec instead of authoring tests

crucihil author protocol_header.h --protocol

CLI Reference

Synopsis

Description

Options

Exit codes

Output format

Framework output

The `--verify` loop

Protocol import mode

Examples

Author a suite for one component (virtual rig gates the output)

The full loop: author + mutation-verify + regenerate weak tests

Emit the suite in your team’s own framework

Import a custom protocol spec instead of authoring tests

See also

​Synopsis

​Description

​Options

​Exit codes

​Output format

​Framework output

​The --verify loop

​Protocol import mode

​Examples

​Author a suite for one component (virtual rig gates the output)

​The full loop: author + mutation-verify + regenerate weak tests

​Emit the suite in your team’s own framework

​Import a custom protocol spec instead of authoring tests

​See also

Synopsis

Description

Options

Exit codes

Output format

Framework output

The `--verify` loop

Protocol import mode

Examples

Author a suite for one component (virtual rig gates the output)

The full loop: author + mutation-verify + regenerate weak tests

Emit the suite in your team’s own framework

Import a custom protocol spec instead of authoring tests

See also