Agent CLI Contract

RAGit now keeps a clearer split between human-readable CLI output and machine-safe command contracts. If you are integrating it into an agent workflow, use these rules first.

Default Rules

Prefer --format json for machine consumers.
Use ragit describe <command> --format json before integrating a command for the first time.
Prefer --view minimal for query, context pack, and memory recall.
Prefer --input <path|-> for agent calls that carry structured payloads.
Run mutating commands with --dry-run first.

Contract Shape

Most major commands can now return a shared envelope:

{
  "command": "query",
  "ok": true,
  "version": "1.1.1",
  "cwd": "/repo/path",
  "data": {},
  "warnings": []
}

That envelope is meant to stay stable even when the human text output changes.

For per-command syntax, payload shapes, and failure notes, use Commands as the detailed reference.

Stable Operational Failures

Typed operational failures keep the same envelope and add a stable error payload:

{
  "command": "query",
  "ok": false,
  "version": "1.1.1",
  "cwd": "/repo/path",
  "data": null,
  "warnings": [],
  "error": {
    "code": "SNAPSHOT_NOT_INDEXED",
    "category": "not_ready",
    "message": "indexed snapshot을 찾을 수 없습니다: 0123456789abcdef0123456789abcdef01234567",
    "retryable": false,
    "details": { "resolvedSha": "0123456789abcdef0123456789abcdef01234567" },
    "recovery": { "command": "ragit ingest --all" }
  }
}

Exit 2: invalid input, such as an invalid, ambiguous, or non-ancestor commit reference.
Exit 3: a required snapshot/base/store is not ready, dirty ingest candidates exist, or repository state moved repeatedly.
Exit 4: a manifest is corrupt or uses an unsupported future schema.
json writes the failure envelope to stdout, text writes the human failure to stderr, and both uses both streams with the same exit status. Unexpected non-operational errors remain exit 1 on stderr.

Snapshot Rules

An omitted --at means the exact current HEAD. Explicit selection accepts only HEAD, a full commit SHA, or a unique hexadecimal commit prefix.
A nearest indexed ancestor may appear in error details as recovery guidance; it is never selected automatically.
Dirty worktree reads use the committed snapshot, exclude uncommitted changes, and report that fact in warnings.
Successful query and context pack data retain snapshotSha and add snapshot; those two resolved SHAs must agree.

Read Commands

query supports positional input or --input <path|-> JSON payloads.
context pack supports positional input or --input <path|-> JSON payloads.
memory recall accepts a goal and can shrink output with --view minimal|default|full.

For agents, start small:

ragit query --input query.json --view minimal --format json
ragit context pack --input context-pack.json --view minimal --format json
ragit memory recall "resume auth flow" --view minimal --format json

Mutating Commands

These commands now support --dry-run so an agent can validate intent before writing:

ingest
hooks install
hooks uninstall
memory wrap
memory promote

Typical pattern:

ragit memory promote --input promote.json --dry-run --format json
ragit memory promote --input promote.json --format json

For ingest --dry-run, inspect dirtyCandidates and wouldFail before apply. memory promote and harness promote create durable documents with ingested: false; review and commit those documents before running ingest.

Memory Caveat

Do not confuse the two memory surfaces:

.ragit/memory/** is the control plane for working state and session history.
docs/memory/** is the searchable corpus that participates in ingest and snapshot retrieval.

That means agents should use memory wrap and memory recall to manage active work, and memory promote only when knowledge is stable enough to become searchable project memory.

These contracts establish snapshot integrity, not complete practical readiness. Exclusive ingest locking, crash recovery, retrieval evaluation, and distribution-matrix validation remain separate concerns.