YeonGyu-Kim
|
40c17d8f2a
|
docs: add SCHEMAS.md — field-level JSON contract for clawable CLI surfaces
Documents the unified JSON envelope contract across all 13 clawable-surface
commands. Extends the parity work (#171) to the field level: every command
that accepts --output-format json must emit predictable field names,
types, and optionality.
Common fields (all envelopes):
- timestamp (ISO 8601 UTC)
- command (argv[1])
- exit_code (0/1/2)
- output_format ('json')
- schema_version ('1.0')
Error envelope (exit 1, failure):
- error.kind (enum: filesystem|auth|session|parse|runtime|mcp|delivery|usage|policy|unknown)
- error.operation (syscall/method name)
- error.target (resource path/name)
- error.retryable (bool)
- error.message (platform error text)
- error.hint (optional: actionable next step)
Not-found envelope (exit 1, not a failure):
- found: false
- error.kind (enum: command_not_found|tool_not_found|session_not_found)
- error.message, error.retryable
Per-command success schemas documented for 13 commands:
list-sessions, delete-session, load-session, flush-transcript,
show-command, show-tool, exec-command, exec-tool, route, bootstrap,
command-graph, tool-pool, bootstrap-graph
Why this matters:
- #171 enforced that commands have --output-format; #172 enforces that
the JSON fields are PREDICTABLE
- Downstream claws can build ONE error handler + per-command jq query,
not special-casing logic per command family
- Field consistency enables generic automation patterns (error dedupe,
failure aggregation, cross-command monitoring)
Related:
- ROADMAP #172 (field-level contract stabilization, Gaebal-gajae priority #1)
- ROADMAP #171 (parity audit CI automation — already landed)
- #164 Stage B (cancellation observability — adds cancel_observed field)
- #164 Stage A (already done — adds stop_reason field to TurnResult)
Fixture/regression testing:
- Golden JSON snapshots: tests/fixtures/json/<command>.json (future)
- Consistency test: test_json_envelope_field_consistency.py (future)
- Versioning: schema_version='1.0' for current; bump to 2.0 for breaking changes
|
2026-04-22 19:13:04 +09:00 |
|