# CommitBrief v1.0.0

> API freeze. CLI surface, JSON schema v1, and rules formats are now under strict semver. `claude-cli` + `gemini-cli` promoted to stable.

Released May 28, 2026

Canonical URL: https://commitbrief.com/changelog/v1.0.0/

---

## Highlights

**v1.0.0 is the API freeze checkpoint.** From here on, CLI flag
surface, JSON schema v1, the `COMMITBRIEF.md` / `OUTPUT.md`
formats, and public config keys all follow strict
[semver](https://semver.org/spec/v2.0.0.html). Breaking changes
wait for v2.x.

If you're upgrading from anywhere on the v0.x line, the
[migration guide](https://github.com/CommitBrief/commitbrief/blob/main/CHANGELOG.md#migration-guide-v0x--v10)
in the CLI repo collects every breaking change since v0.9.x.

## Added

- **`claude-cli` and `gemini-cli` providers promoted to stable.**
  README documents both alongside the four API providers; the
  v0.9.0 "experimental" disclaimer is gone. The plain-text emit
  pipeline closed the last reliability gaps — `--output` routes
  correctly, the host CLI's version is memoised + bounded, and
  the prompt transport for claude-cli switched to stdin so
  ARG_MAX is no longer a ceiling.

- **gosec security scan + `make security-check`.** Static security
  analysis runs on every push to main and on a weekly schedule
  (`.github/workflows/security.yml`). Local devs get the same
  wrapper via `scripts/security-scan.sh`. The exclusion set
  (G304/G306/G301/G204/G101/G122) is documented inline with
  one-paragraph rationale per rule. High-confidence findings
  (G115 etc.) fail the scan.

- **README "Stability" section.** Declares the v1.0.0 API freeze
  scope and links to the v0.x → v1.0 migration guide.

- **BENCHMARKS.md baseline snapshot.** Captures diff-pipeline and
  cache-hit numbers at the v1.0.0-rc.1 freeze point. Used as a
  regression detector — a future 2× slowdown is the trigger for
  an investigation.

- **`make check` target.** Runs every guard CI runs, in CI order,
  bailing on the first failure. Single entry-point for "is this
  push-ready?".

- **`COMMITBRIEF_CONFIG` environment variable documented.**
  Setting it to an absolute path replaces the default
  `~/.commitbrief/config.yml` lookup — useful for ephemeral CI
  environments and reproducible tests.

## Changed

- **`Diff.IsMerge` field and `cli.warn.merge_commit` catalog key
  removed.** The merge-commit warning was retired with the scope-
  flag collapse in v0.9.0 — `commitbrief diff <merge-sha>` gives
  first-parent semantics with no special prompt (same as
  `git diff <merge-sha>`). Library consumers reading the field
  need to drop it.

## Fixed

- **Gemini provider hardens int→int32 conversion for max-output
  tokens.** A value above `math.MaxInt32` would silently wrap to
  negative; now bounded to `[1, math.MaxInt32]` with the default
  falling back to 4096. Found via gosec G115 during the v1.0.0-rc.1
  security audit.

- **`KeyMeta.DiffHash` and `KeyMeta.SystemPromptHash` carry real
  SHA-256 digests.** Pre-v1.0.0-rc.1 the diff hash stored the
  first 16 hex chars of the composite cache key (NOT a diff hash)
  and the system-prompt hash was always empty. Both fields now
  match what the configuration docs advertise.

- **Generated git hooks embed the absolute path to commitbrief.**
  macOS GUI git clients (Tower, GitHub Desktop, Fork, JetBrains
  IDEs) run hooks with a stripped `$PATH` that typically omits
  `/opt/homebrew/bin`, so `exec commitbrief --staged …` silently
  failed to launch. `install-hook` now resolves the running binary
  via `os.Executable` + `filepath.EvalSymlinks` and embeds the
  result as a single-quoted token. Survives `brew upgrade` (which
  swaps the keg symlink target).