# Contracts

This document summarizes the stable machine-facing contracts exposed by `smart-commit CLI`.

If you are trying the CLI for the first time, start with [`getting-started.md`](./getting-started.md). This document is mainly for machine integrations and contract consumers.

For formal JSON Schema output, use:

```bash
smart-commit schema print --target bridge
smart-commit schema print --target report-generate
```

## Shared Rules

- All machine-facing JSON payloads include `schemaVersion`
- Parse stdout as JSON
- Treat stderr as supplemental human-readable context
- Prefer `status` and `error.code` over string matching in `summary`

## `config resolve`

Command:

```bash
smart-commit config resolve --config ./smart-commit.json
```

Stable top-level fields:

- `schemaVersion`
- `status`
- `command`
- `runtime`
- `config`

Use it to validate merged config before wiring `bridge` or `report generate` into automation.

Contract consumers can safely read newly added resolved settings such as `config.connection.llmResponseCorrectionRetryCount`, `config.passHistory.writeStage`, `config.review.skill.id`, `config.commitMessage.structure`, and `config.pullRequestSummary.enabled` from the returned `config` object.

## `bridge`

Command:

```bash
smart-commit bridge --repo /path/to/repo --config ./smart-commit.json
```

Stable top-level fields:

- `schemaVersion`
- `status`
- `command`
- `repositoryPath`
- `phase`
- `didCommit`
- `didPush`
- `commitSha`
- `passHistory`
- `pullRequestSummary`
- `reviewDecision`
- `score`
- `summary`
- `error`

Stable nested fields often used by automations:

- `passHistory.eventType`
- `pullRequestSummary.generated`
- `pullRequestSummary.outputFilePath`
- `reviewDetails`

`passHistory.writeStage` controls when a pass-history record is first allowed to exist. Once a record exists, later successful stages update that same record, so `passHistory.eventType` always reflects the furthest successful stage reached by the run.

`passHistory.eventType` semantics:

- `review_passed`
  Review passed, and no later success stage was reached.
- `commit_completed`
  Review passed and a local commit was created, but no later push success stage was reached.
- `commit_push_completed`
  Review passed, a local commit was created, and the current branch was pushed.
- `null`
  Pass history is disabled or no pass-history record was written.

For example, when `passHistory.writeStage = "commit_completed"`, a successful local commit can still leave `passHistory.eventType = "commit_completed"` if the later push cannot start, fails, or times out. When `passHistory.writeStage = "commit_push_completed"`, those same push failures keep `passHistory.eventType = null` because no record is written.

`pullRequestSummary` is always present in bridge output. When `pullRequestSummary.enabled = true`, the CLI attempts generation only after the review/commit/push action for that run succeeds. Generation failures are reported in `pullRequestSummary.error` and do not change the already successful bridge exit code.

Status semantics:

- `ready`
  Returned for dry-run preflight success.
- `passed`
  Returned when execution succeeds through review, or through commit/push depending on config.
- `blocked`
  Returned for expected business outcomes such as review blocking or staged-diff gating.
- `error`
  Returned for configuration or runtime failures.

Important `error.code` values:

- `CONFIG_ERROR`
- `RUNTIME_ERROR`
- `NO_CHANGES`
- `NO_STAGED_DIFF`
- `WOULD_AUTO_STAGE`
- `COMMIT_MESSAGE_REQUIRED`
- `COMMIT_MESSAGE_INVALID`
- `REVIEW_BLOCKED`

Recommended automation behavior:

- continue on `ready` or `passed`
- stop on `blocked` and surface `error.code` plus `summary`
- fail on `error`

## `report generate`

Command:

```bash
smart-commit report generate --repo /path/to/repo --period weekly
```

Supported `periodType` values are `daily`, `yesterday`, `weekly`, `monthly`, `quarterly`, and `yearly`.

Stable top-level fields:

- `schemaVersion`
- `status`
- `command`
- `repositoryPath`
- `periodType`
- `passHistoryFilePath`
- `outputFilePath`
- `renderMode`
- `reportProvider`
- `warnings`
- `facts`
- `summary`
- `error`

Important `facts.totals` fields:

- `reviewPassed`
  Count of successful records whose final review decision is `pass`.
- `commitCompleted`
  Count of records with `eventType = "commit_completed"`.
- `commitPushCompleted`
  Count of records with `eventType = "commit_push_completed"`.

`renderMode` semantics:

- `local`
  Local deterministic Markdown generation was used.
- `ai`
  AI-enhanced report generation succeeded.
- `ai-fallback-local`
  AI generation failed and the CLI fell back to local Markdown.

Recommended automation behavior:

- archive or upload `outputFilePath` on success
- inspect `warnings` when `renderMode` is `ai-fallback-local`
- use `facts.totals.commitCompleted` and `facts.totals.commitPushCompleted` separately if local commit completion and remote push completion need different downstream handling
- fail on `status: "error"`

## Versioning Guidance

- treat `schemaVersion` as the primary compatibility gate
- use JSON Schema for strict validation when integrating with agents or services
- expect additive fields to be the preferred evolution path