Agent CLI Contract

RAGit은 이제 사람용 출력과 기계용 계약을 더 분명하게 분리합니다. 에이전트 워크플로에 붙인다면 아래 규칙부터 기준으로 삼으시면 됩니다.

기본 규칙

기계 호출은 기본적으로 --format json을 우선합니다.
처음 붙이는 명령은 ragit describe <command> --format json으로 계약부터 읽습니다.
query, context pack, memory recall은 기본적으로 --view minimal을 우선합니다.
구조화된 payload가 있으면 --input <path|->를 우선합니다.
mutating 명령은 먼저 --dry-run으로 검증합니다.

계약 형태

주요 명령은 공통 envelope를 반환할 수 있습니다.

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

사람용 텍스트 출력이 바뀌더라도, 에이전트는 이 envelope를 안정적인 계약으로 읽으면 됩니다.

명령별 구문, payload 예시, 실패 주의사항은 Commands에서 자세히 보실 수 있습니다.

안정적인 Operational Failure

Typed operational failure는 같은 envelope를 유지하면서 안정적인 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, ambiguous, non-ancestor commit ref 같은 잘못된 입력입니다.
Exit 3: 필요한 snapshot/base/store가 준비되지 않았거나 dirty ingest candidate가 있거나 repository state가 반복해서 이동한 경우입니다.
Exit 4: manifest가 손상됐거나 지원하지 않는 future schema를 사용하는 경우입니다.
json은 failure envelope를 stdout에, text는 사람이 읽는 failure를 stderr에 기록합니다. both는 같은 exit status로 두 stream을 모두 사용합니다. 예상하지 못한 non-operational error는 기존처럼 stderr와 exit 1을 사용합니다.

Snapshot 규칙

--at을 생략하면 정확한 현재 HEAD를 뜻합니다. Explicit selection은 HEAD, full commit SHA, unique hexadecimal commit prefix만 허용합니다.
nearest indexed ancestor는 error details의 recovery hint일 뿐 자동 선택 결과가 아닙니다.
Dirty worktree 조회는 커밋된 snapshot을 사용하고 uncommitted change를 제외하며 그 사실을 warnings에 보고합니다.
성공한 query와 context pack data는 기존 snapshotSha를 유지하면서 snapshot을 추가하고, 두 resolved SHA는 같아야 합니다.

조회 계열 명령

query는 positional 입력과 --input <path|-> JSON payload를 모두 지원합니다.
context pack도 positional 입력과 --input <path|-> JSON payload를 모두 지원합니다.
memory recall은 goal을 받아 --view minimal|default|full로 출력량을 조절할 수 있습니다.

에이전트에서는 먼저 작은 패킷부터 사용하십시오.

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

변경 계열 명령

아래 명령은 --dry-run을 지원하므로, 에이전트가 쓰기 전에 먼저 계획을 검증할 수 있습니다.

ingest
hooks install
hooks uninstall
memory wrap
memory promote

권장 패턴은 다음과 같습니다.

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

ingest --dry-run에서는 apply 전에 dirtyCandidates와 wouldFail을 확인하십시오. memory promote와 harness promote는 ingested: false 상태로 durable document를 생성하므로, 문서를 검토하고 커밋한 뒤 ingest를 실행해야 합니다.

Memory 주의점

두 메모리 표면을 혼동하지 마십시오.

.ragit/memory/**는 working state와 session history를 위한 control plane입니다.
docs/memory/**는 ingest와 snapshot retrieval에 참여하는 searchable corpus입니다.

즉, 에이전트는 현재 작업을 다룰 때 memory wrap과 memory recall을 사용하고, 충분히 안정화된 지식만 memory promote로 searchable project memory로 승격해야 합니다.

이 계약은 snapshot integrity를 확립하지만 완전한 practical readiness를 보장하지는 않습니다. Exclusive ingest locking, crash recovery, retrieval evaluation, distribution matrix 검증은 별도 관심사로 남아 있습니다.