compare-cli: Instructions file for Codex

AGENTS.md

This file describes the stable surface of compare-cli for LLM agents and downstream tooling. The exit codes and --json shape documented here are stable across v1.x minor releases.

Output contract

compare-cli is a deterministic pre-signature gate: given two contract versions (BASE = what was agreed, CANDIDATE = what's being put forward), it classifies the drift between them and reports it via the exit code.

stdout is the report. Human-readable when stdout is a TTY (with ANSI color), structured JSON when --json is set, plain text otherwise.

stderr is the side channel. Warnings, the --why block, and error messages go to stderr. --silent / -q suppresses all stderr output; exit codes are unchanged. Argument-parse errors always print on the real stderr regardless of --silent.

Exit codes

The exit code is the verdict — these are drift severities, not just error/success, so branch on them (don't assume the suite's common scheme):

Exit	exit_class	Meaning
0	clean	No drift detected. Every clause matches. Safe to sign.
1	n/a	I/O error — input not found, unreadable, malformed .docx/.pdf.
2	substantive	Substantive drift, or --strict/--strict-cosmetic was tripped.
3	cosmetic / typographic	Cosmetic-only or typographic-only drift. Informational.
4	moved	Clause(s) moved but content identical.

--json output shape (stable across v1.x)

{
  "ok": true,
  "exit_class": "clean",
  "exit_code": 0,
  "base": {
    "path": "negotiated.docx",
    "format": "docx",
    "lossiness": "none",
    "clauses_total": 12,
    "track_changes": []
  },
  "candidate": {
    "path": "ready-to-sign.pdf",
    "format": "pdf",
    "lossiness": "extracted",
    "clauses_total": 12,
    "track_changes": []
  },
  "summary": {
    "clauses_total": 12,
    "clauses_changed": 0,
    "clauses_moved": 0,
    "clauses_added": 0,
    "clauses_removed": 0,
    "differences": {
      "cosmetic": 0,
      "typographic": 0,
      "substantive": 0,
      "added": 0,
      "removed": 0,
      "moved": 0
    },
    "suppressed_by_filter": 0
  },
  "differences": [],
  "warnings": []
}