# Contracts

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

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-host-agent schema print --target bridge
smart-commit-host-agent schema print --target commit-message-generate
smart-commit-host-agent schema print --target report-generate
smart-commit-host-agent schema print --target pull-request-create
smart-commit-host-agent schema print --target pull-request-review
smart-commit-host-agent schema print --target my-pull-request-batch-review
smart-commit-host-agent schema print --target config-file
smart-commit-host-agent schema print --target config-resolve
```

Schemas never include LLM `connection` fields.

## 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`
- `status: "needs_host_agent"` is a normal pause, not a failure. Write the turn response, then resume with `--session`

When `status` is `needs_host_agent`, these fields are the resume contract:

- `sessionPath`
- `requestPath`
- `turnId`
- `purpose` (when the command emits it)

Exit codes:

- `0`: success
- `2`: blocked
- `3`: config / input error
- `4`: runtime error
- `10`: `needs_host_agent`

## `config resolve`

Command:

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

Stable top-level fields:

- `schemaVersion`
- `status`
- `command`
- `config`
- `summary`

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

`status` semantics:

- `resolved`
  Config merged and validated.
- `error`
  Invalid config, missing env (except optional `pullRequest.authToken`), or rejected LLM flags.

`config` never contains `connection`. `pullRequest.authToken` is redacted in output when set.

## `bridge`

Command:

```bash
smart-commit-host-agent bridge --repo /path/to/repo --config ./smart-commit.host-agent.json --output json
smart-commit-host-agent bridge --review-only --repo /path/to/repo --session-base /tmp/scha --output json
```

Stable top-level fields:

- `schemaVersion`
- `status`
- `command`
- `phase`
- `repositoryPath`
- `commitMessage`
- `score`
- `threshold`
- `sessionPath`
- `requestPath`
- `turnId`
- `purpose`
- `summary`
- `error`

`status` semantics:

- `needs_host_agent`
  A turn request was written. Fill the response and resume with `--session`.
- `ready`
  Returned for dry-run preflight success when supported.
- `passed`
  Review passed, or the configured commit/push path completed.
- `blocked`
  Expected business outcomes such as review blocking or staged-diff gating.
- `error`
  Configuration or runtime failures.

Recommended automation behavior:

- continue on `passed` or `ready`
- on `needs_host_agent`, write `turns/NNNN.response.json` and resume
- stop on `blocked` and surface `error.code` plus `summary`
- fail on `error`

## `commit-message generate`

Command:

```bash
smart-commit-host-agent commit-message generate --repo /path/to/repo --session-base /tmp/scha --output json
```

This command resolves the final commit message without running review, commit, push, or PR/MR creation.

Stable top-level fields:

- `schemaVersion`
- `status`
- `command`
- `commitMessage`
- `commitMessageSource`
- `sessionPath`
- `requestPath`
- `turnId`
- `purpose`
- `summary`
- `error`

`--commit-message` skips the Host-Agent turn and validates the provided message.

## `pull-request create`

Command:

```bash
smart-commit-host-agent pull-request create --repo /path/to/repo --config ./smart-commit.host-agent.json --output json
```

Stable top-level fields:

- `schemaVersion`
- `status`
- `command`
- `platform`
- `title`
- `description`
- `url`
- `dryRun`
- `sessionPath`
- `requestPath`
- `turnId`
- `purpose`
- `summary`
- `error`

Requires `pullRequest.authToken` and a forge `origin` remote. `--dry-run` skips the create POST.

When the branch range has exactly one commit, the title reuses that commit subject. Explicit `--title` / `--description` are not overwritten.

Recommended automation behavior:

- archive or surface `url` on success
- use `--dry-run` before first enabling provider writes
- treat `needs_host_agent` as the pr-content turn pause
- fail on `status: "error"`

## `pull-request review`

Command:

```bash
smart-commit-host-agent pull-request review https://github.com/org/repo/pull/123 \
  --repo /path/to/repo --config ./smart-commit.host-agent.json --output json
```

Stable top-level fields:

- `schemaVersion`
- `status`
- `command`
- `url`
- `platform`
- `number`
- `score`
- `threshold`
- `passed`
- `summaryCommentAction`
- `inlineCommentAction`
- `sessionPath`
- `requestPath`
- `turnId`
- `purpose`
- `summary`
- `error`

`status` semantics:

- `needs_host_agent`
  Review turn is waiting for a Host-Agent response.
- `passed`
  The review completed and passed the configured threshold.
- `blocked`
  The review completed but did not pass the configured threshold.
- `error`
  Configuration or runtime validation failed.

`--dry-run` still runs the review turn, but skips comments, approval, and merge. `--fixture-pr` overrides the network for offline tests.

Recommended automation behavior:

- use `--dry-run` for first validation
- inspect `summaryCommentAction` and `inlineCommentAction` when publishing comments matters
- fail on `status: "error"`

## `my-pull-request list`

Command:

```bash
smart-commit-host-agent my-pull-request list --config ./smart-commit.host-agent.json --output json
```

This command requires `pullRequest.authToken` and does not emit Host-Agent turns.

Use `--my-pull-request-list-scope account|workspace`, `--my-pull-request-list-kinds`, and `--my-pull-request-remote-host` to control the query. With `listScope=account` and a non-empty `remoteHost`, no local git repository is required.

## `my-pull-request batch-review`

Command:

```bash
smart-commit-host-agent my-pull-request batch-review --config ./smart-commit.host-agent.json \
  --session-base /tmp/scha --output json
```

Stable top-level fields:

- `schemaVersion`
- `status`
- `command`
- `totalListed`
- `outcomes`
- `cancelledRemaining`
- `dryRun`
- `sessionPath`
- `requestPath`
- `turnId`
- `purpose`
- `summary`

`status` semantics:

- `needs_host_agent`
  The current item is waiting for a Host-Agent turn. Progress is stored in `batch-review-state.json`; completed URLs are skipped on resume.
- `ok`
  The batch finished (including an empty list).
- `error`
  Configuration or runtime validation failed.

Exit `2` when any reviewed item did not pass. Exit `10` while a turn is pending.

## `report generate`

Command:

```bash
smart-commit-host-agent report generate --repo /path/to/repo --period weekly --output json
smart-commit-host-agent report generate --repo /path/to/repo --period custom --start-date 2026-04-01 --end-date 2026-04-09 --output json
```

Supported `periodType` values are `daily`, `yesterday`, `weekly`, `last-week`, `monthly`, `last-month`, `quarterly`, `last-quarter`, `yearly`, and `custom`.

Stable top-level fields:

- `schemaVersion`
- `status`
- `command`
- `repositoryPath`
- `periodType`
- `passHistoryFilePath`
- `outputFilePath`
- `renderMode`
- `reportProvider`
- `sessionPath`
- `requestPath`
- `turnId`
- `purpose`
- `summary`
- `error`

`renderMode` semantics:

- `local`
  Local deterministic Markdown generation was used.
- `ai`
  AI-enhanced report generation succeeded via a Host-Agent turn.
- `ai-fallback-local`
  AI generation failed (non-turn) and the CLI fell back to local Markdown.

`--report-ai` / `reporting.ai.enabled` emit `needs_host_agent` with `purpose: "report"`. There is no LLM HTTP path.

Recommended automation behavior:

- archive or upload `outputFilePath` on success
- inspect `renderMode` when AI reporting is enabled
- fail on `status: "error"`

## Versioning Guidance

- treat `schemaVersion` as the primary compatibility gate
- use JSON Schema (`schema print`) for strict validation when integrating with agents or services
- expect additive fields to be the preferred evolution path
- `needs_host_agent` plus `--session` is a stable skill-loop contract