copperhead

# cli-surface — Delta Spec

## ADDED Requirements

### Requirement: `check` reports legibility advisories

`check` SHALL run the deterministic legibility checker over the configured schematic and report its findings grouped by severity. The findings SHALL NOT affect `check`'s exit code at any severity, so a repo that passes today continues to pass. `check` SHALL remain LLM-free and network-free with the checker included.

#### Scenario: Illegible schematic still exits zero (AC-16.25)

- **WHEN** `check` runs on a repo whose schematic has error-severity legibility findings but clean ERC and DRC
- **THEN** the findings are printed under a legibility heading and the exit code is 0

#### Scenario: Determinism is preserved

- **WHEN** `check` runs with the checker enabled
- **THEN** no language-model call and no network request is made

### Requirement: `--json` carries legibility findings and score

`check --json` SHALL emit a `legibility` object of the shape `{findings, counts, skipped, disabled, score}`: `findings` is an array of checker findings, each `{kind, severity, sheet, at: {x, y}, refs, detail}` where `kind` is one of the checker's stable kind identifiers, `severity` is `error` or `advisory`, `sheet` and `detail` are strings, `at` carries millimetre coordinates, and `refs` is an array of strings; `counts` is `{error, advisory}` with integer totals; `skipped` is an array of `{family, reason}` records for checks not evaluated (for example page-relative checks on an unrecognized paper size); `disabled` is an array of family identifiers turned off in config; `score` is `{composite, metrics, cap}` where `composite` is the 0-100 weighted value, `metrics` is the per-metric breakdown (raw value, weight, contribution), and `cap` names the applied error-finding cap or is null. The score SHALL be advisory and SHALL NOT affect the exit code. The `legibility` key SHALL always be present: with empty arrays, zero counts, and a null score when the schematic is clean or absent, and with every family recorded as skipped when no schematic is configured.

#### Scenario: Machine-readable findings

- **WHEN** `check --json` runs on a repo with two error-severity findings
- **THEN** stdout contains a `legibility` object listing both findings with their kind, severity, sheet, and coordinates, and a count of 2 at error severity

#### Scenario: No schematic configured

- **WHEN** `check --json` runs in a repo whose config names no schematic
- **THEN** the `legibility` object is present with an empty findings list, zero counts, a null score, and every family recorded as skipped

#### Scenario: Score rides along without gating (AC-16.26)

- **WHEN** `check --json` runs on a repo with a drafted schematic and a low composite
- **THEN** the `score` object carries the composite and breakdown and the exit code is unaffected

### Requirement: `draft schematic` command

`copperhead draft schematic` SHALL run the drafting engine over the project's netlist-intent IR and write the configured schematic, printing the draft report. It SHALL be deterministic, LLM-free, and network-free, and SHALL exit non-zero with the numbered finding list when IR validation fails, leaving any existing schematic untouched. `draft` and `score` SHALL take the artifact as a noun subcommand (`schematic` today; `pcb` is reserved for layout drafting), and the bare verb SHALL list its subcommands rather than guess.

#### Scenario: Draft from the command line

- **WHEN** `copperhead draft schematic` runs in a project with a valid IR
- **THEN** the schematic is regenerated byte-identically for unchanged IR and the report is printed

#### Scenario: Validation failure exits non-zero

- **WHEN** `copperhead draft schematic` runs with an IR that fails validation
- **THEN** the exit code is non-zero, the findings are printed, and the schematic file is unchanged

### Requirement: `score schematic` command

`copperhead score schematic` SHALL run the deterministic scorer over the configured schematic and print the score JSON (composite, per-metric breakdown, applied caps). It SHALL be LLM-free and network-free, and its exit code SHALL NOT depend on the score value.

#### Scenario: Score from the command line

- **WHEN** `copperhead score schematic` runs against a configured schematic
- **THEN** the score JSON is printed and the exit code is 0 regardless of the composite