From 1a03359bb478730fe1fe5fead802edb52baee6d7 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Thu, 23 Apr 2026 05:11:14 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=20=E2=80=94=20fix=20target/cu?= =?UTF-8?q?rrent=20boundary=20collapse=20(#165=20Option=20A)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md was documenting the v2.0 target schema as if it were current binary behavior. This misled validator/harness implementers into assuming the Rust binary emits timestamp, command, exit_code, output_format, schema_version fields when it doesn't. Fixed by explicitly marking the boundary: 1. SCHEMAS.md section: now clearly labels 'target v2.0 design' and lists both v1.0 (actual binary) and v2.0 (target) field shapes 2. Clawable commands requirements: now explicitly separates v1.0 (current) and v2.0 (post-FIX_LOCUS_164) envelope requirements 3. Added inline migration note pointing to FIX_LOCUS_164.md This closes #165 as the third P0 doc-truthfulness fix (Option A: preserve current truth, add v2.0 target as separate labeled section). P0 doc-truthfulness family pattern (all three related to #164 envelope divergence): - #78 USAGE.md: active misdocumentation (fixed cycle #78) - #79 ERROR_HANDLING.md: copy-paste trap (fixed cycle #79) - #165 CLAUDE.md: target/current boundary collapse (fixed cycle #81) --- CLAUDE.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5c723ee..5ae73a0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -60,13 +60,16 @@ python3 -m mypy src/ --ignore-missing-imports 2>&1 | tail -5 - `test_submit_message_*.py` — budget, cancellation contracts - `test_*_cli.py` — command-specific JSON output validation -- **`SCHEMAS.md`** — canonical JSON contract - - Common fields (all envelopes): timestamp, command, exit_code, output_format, schema_version - - Error envelope shape - - Not-found envelope shape +- **`SCHEMAS.md`** — canonical JSON contract (**target v2.0 design; see note below**) + - **Target v2.0 common fields** (all envelopes): timestamp, command, exit_code, output_format, schema_version + - **Current v1.0 binary fields** (what the Rust binary actually emits): flat top-level `kind` + verb-specific fields OR `{error, hint, kind, type}` for errors + - Error envelope shape (target v2.0: nested error object) + - Not-found envelope shape (target v2.0) - Per-command success schemas (14 commands documented) - Turn Result fields (including cancel_observed as of #164 Stage B) + > **Important:** SCHEMAS.md describes the **v2.0 target envelope**, not the current v1.0 binary behavior. The binary does NOT currently emit `timestamp`, `command`, `exit_code`, `output_format`, or `schema_version` fields. See [`FIX_LOCUS_164.md`](./FIX_LOCUS_164.md) for the migration plan (Phase 1: dual-mode flag; Phase 2: default bump; Phase 3: deprecation). + - **`.gitignore`** — excludes `.port_sessions/` (dogfood-run state) ## Key concepts @@ -75,9 +78,12 @@ python3 -m mypy src/ --ignore-missing-imports 2>&1 | tail -5 Every clawable command **must**: 1. Accept `--output-format {text,json}` -2. Return JSON envelopes matching SCHEMAS.md -3. Use common fields (timestamp, command, exit_code, output_format, schema_version) -4. Exit 0 on success, 1 on error/not-found, 2 on timeout +2. Return JSON envelopes (current v1.0: flat shape with top-level `kind`; target v2.0: nested with common fields per SCHEMAS.md) +3. **v1.0 (current):** Emit flat top-level fields: verb-specific data + `kind` (verb identity for success, error classification for errors) +4. **v2.0 (target, post-FIX_LOCUS_164):** Use common wrapper fields (timestamp, command, exit_code, output_format, schema_version) with nested `data` or `error` objects +5. Exit 0 on success, 1 on error/not-found, 2 on timeout + +**Migration note:** The Python reference harness in `src/` was written against the v2.0 target schema (SCHEMAS.md). The Rust binary in `rust/` currently emits v1.0 (flat). See [`FIX_LOCUS_164.md`](./FIX_LOCUS_164.md) for the full migration plan and timeline. **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, turn-loop