# CLI Contract: Clean Release Compliance Subsystem Redesign

## Command Groups

### Candidate

```bash
clean-release candidate register --candidate-id <id> --version <version> --source-snapshot <ref> [--build-id <id>] [--provenance-ref <ref>] [--actor <actor>]
clean-release candidate import-artifacts --candidate-id <id> --input <artifacts.json> [--actor <actor>]
clean-release candidate show --candidate-id <id> [--json]
clean-release candidate list [--json]
```

### Manifest

```bash
clean-release manifest build --candidate-id <id> [--actor <actor>] [--json]
clean-release manifest show --manifest-id <id> [--json]
clean-release manifest list --candidate-id <id> [--json]
```

### Compliance

```bash
clean-release compliance run --candidate-id <id> [--manifest-id <manifest_id>] [--actor <actor>] [--json]
clean-release compliance status --run-id <run_id> [--json]
clean-release compliance report --run-id <run_id> [--json]
clean-release compliance violations --run-id <run_id> [--json]
```

### Release

```bash
clean-release release approve --candidate-id <id> --report-id <report_id> --actor <actor> [--comment <text>] [--json]
clean-release release reject --candidate-id <id> --report-id <report_id> --actor <actor> [--comment <text>] [--json]
clean-release release publish --candidate-id <id> --report-id <report_id> --channel <channel> --actor <actor> [--json]
clean-release release revoke --publication-id <publication_id> --actor <actor> --reason <text> [--json]
```

### Demo

```bash
clean-release demo seed [--profile <name>] [--json]
clean-release demo reset [--json]
```

## Output Rules

- Default mode prints concise operator-friendly summaries.
- `--json` prints machine-readable DTO payloads.
- Errors print machine-readable codes and short text to stderr.
- Compliance run creation returns `run_id` and `task_id` immediately.
- If `--manifest-id` is omitted, CLI uses the latest manifest for the candidate or returns invalid input when no manifest exists.

## Actor Mapping Rule

- CLI always accepts external actor context as `--actor`.
- Interface adapters map `--actor` to internal domain fields by action type:
  - candidate register -> `created_by`
  - manifest build -> `created_by`
  - compliance run -> `requested_by`
  - release approve/reject -> `decided_by`
  - release publish -> `published_by`
  - release revoke -> revocation actor field in command payload or audit event
- This mapping is deterministic and hidden from operators; CLI does not expose multiple actor flag names for different commands.

## Exit Codes

- `0`: Passed / successful mutation / successful read.
- `1`: Business blocked (`BLOCKED`, forbidden publish/approve because of valid business rule).
- `2`: Invalid input (`candidate not found`, `manifest missing`, malformed request).
- `3`: System error (`policy store unavailable`, persistence failure, unexpected exception).

## CLI Behavior Constraints

- Business actions are explicit CLI arguments, not env-driven side effects.
- CLI supports headless operation and never requires curses/TTY.
- CLI does not synthesize policy or registry values locally.