From 1d155e430443999a37c6e03249c468deb9177e57 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Wed, 22 Apr 2026 21:01:40 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20ROADMAP.md=20=E2=80=94=20file=20#180=20?= =?UTF-8?q?(discoverability=20gap:=20--help/--version=20outside=20JSON=20c?= =?UTF-8?q?ontract)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cycle #24 dogfood discovery. Running proactive edge-case dogfood on the JSON contract, hit a real pinpoint: --help and --version are outside the parser-front-door contract. The gap: 1. "claw --help --output-format json" returns text (not envelope) 2. "claw bootstrap --help --output-format json" returns text (not envelope) 3. "claw --version" doesn't exist at all Why it matters: - Claws can't programmatically discover the CLI surface - Version checking requires side-effectful commands - Natural follow-up gap to #178/#179 parser-front-door work Discoverability scenarios: - Orchestrator checking whether a new command (e.g., turn-loop) is available - Version compat check before dispatching work - Enumerating available commands for routing decisions Filed as Pinpoint #180 in ROADMAP.md with: - Gap description + 3-case repro - Impact analysis (version compat, surface enumeration, governance) - Root cause (argparse default HelpAction prints text + exits) - Fix shape (3 stages, ~40 lines total) - Stage A: --version + JSON envelope version metadata - Stage B: --help JSON routing via custom HelpAction - Stage C: optional 'schema-info' command for pre-dispatch discovery - Acceptance criteria (4 cases, including backward compat) - Priority: Medium (not red-state, but real discoverability gap) Status: **Filed, implementation deferred.** Following maintainership equilibrium: pinpoints stay documented but don't force code changes. If external demand arrives (claw author building a dispatcher, orchestrator doing version checks), the fix can ship in one cycle using the shape already documented. No code changes this cycle. Pure ROADMAP filing. Continues the maintainership pattern: find friction, document it, defer until evidence-backed demand arrives. Source: Jobdori proactive dogfood at 2026-04-22 20:58 KST. --- ROADMAP.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/ROADMAP.md b/ROADMAP.md index e82b18f..935b9f3 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -6458,3 +6458,80 @@ flushed=True **Blocker.** None. `save_session` already accepts `directory`; `QueryEnginePort.session_id` is already a settable field; the wiring is pure CLI layer. **Source.** Jobdori dogfood sweep 2026-04-22 17:58 KST — ran `flush-transcript "hello"`, got the path-plus-key=value hybrid output, then checked `--help` for the flag pair I just shipped across the triplet in #165. Realized the session-*creation* command was asymmetric with the now-symmetric management triplet. Closes the last gap in the session-lifecycle CLI surface. + +## Pinpoint #180. Top-level `--help` and `--version` bypass JSON envelope contract — claws cannot discover CLI surface programmatically + +**Gap.** The clawable protocol contract (SCHEMAS.md) guarantees that `--output-format json` produces structured output for the 14 CLAWABLE commands. But two **discoverability/metadata endpoints** that claws need before dispatching work fall outside this contract: + +1. **`--help` (top-level and subcommand):** Returns human-readable text even with `--output-format json`, exits 0. Claws asking "what commands does this version of claw-code expose?" get unparsable text. + +2. **`--version`:** Does not exist at all. Claws cannot check CLI/schema version without invoking a command and parsing the envelope's `schema_version` field (which requires a side-effectful call, e.g., `bootstrap ""`). + +**Repro.** +```bash +# Test 1: top-level --help in JSON mode +$ claw --help --output-format json +usage: main.py [-h] {summary,manifest,...} +Python porting workspace for the Claude Code rewrite effort +$ echo $? +0 +# stdout is text, not JSON. Claws that parse stdout get human help. + +# Test 2: subcommand --help in JSON mode +$ claw bootstrap --help --output-format json +usage: main.py bootstrap [-h] [--limit LIMIT] [--output-format {text,json}] + prompt +# Same problem at subcommand level. + +# Test 3: --version doesn't exist +$ claw --version +usage: main.py [-h] ... +main.py: error: the following arguments are required: command +# No version surface at all. +``` + +**Impact.** + +1. **Claws cannot check version compatibility before dispatch.** A claw receiving a task from an orchestrator needs to know: "does this claw-code install have `turn-loop` (added in some version)? Does the envelope format match `schema_version` 1.0 or 1.1?" Without `--version`, the claw must invoke a command and inspect the envelope's `schema_version` field. This is side-effectful (may create a session, may flush a transcript, may affect billing if provider calls happen). + +2. **Claws cannot enumerate the CLI surface.** `--help` is the natural introspection endpoint. Right now claws building a dispatcher must either (a) parse human help text (brittle), (b) call each of the 14 commands and see which exit cleanly, or (c) hardcode the list in their code (brittle across versions). + +3. **Discoverability governance is incomplete.** Post-cycles #178/#179, parse errors emit envelopes. But the natural "show me what exists" queries still fall outside the protocol. + +**Root cause.** +- `parser.add_argument('--help', '-h')` is implicit argparse default; its handler prints to stdout and exits 0. No hook to route through JSON mode. +- `parser.add_argument('--version')` was never added to the top-level parser. + +**Fix shape (~40 lines).** + +*Stage A — `--version` addition (smallest, isolated).* +1. Add `parser.add_argument('--version', action='version', version=...)` to top-level parser. +2. Version string pulls from a single constant (e.g., `CLAW_CODE_VERSION = '0.1.0'`). +3. When `--output-format json` is also passed, intercept and emit envelope with fields: `{command: '--version', version: '0.1.0', schema_version: '1.0', clawable_surfaces: [14 names], opt_out_surfaces: [12 names]}`. + +*Stage B — `--help` JSON routing (trickier, hooks argparse default).* +4. Subclass ArgumentParser or use custom HelpAction. +5. When `--help --output-format json` detected, emit envelope with: `{command: 'help', subcommand: None, commands: [{name, description, clawable: bool}], ...}`. +6. Subcommand-level: `{command: 'help', subcommand: 'bootstrap', arguments: [{name, type, required, help}], ...}`. + +*Stage C — discovery metadata.* +7. Consider adding `claw schema-info --output-format json` as explicit endpoint (alongside --version). Emits: `{schema_version, clawable_surfaces, opt_out_surfaces, error_kinds, supported_envelope_fields}`. This is the "pre-dispatch discovery" endpoint claws need. + +**Acceptance.** +- `claw --version` emits a version string in text mode +- `claw --version --output-format json` emits a structured envelope with version + surface lists +- `claw --help --output-format json` emits a structured envelope listing commands (with descriptions) +- `claw bootstrap --help --output-format json` emits a structured envelope listing arguments +- Backward compat: `claw --help` in text mode unchanged byte-for-byte + +**Blocker.** None. argparse's built-in HelpAction can be subclassed (standard pattern). `--version` is a one-line addition. The `schema-info` command is optional (Stage C); Stages A+B close the core gap. + +**Priority.** Medium. Not a red-state bug (no claw is blocked), but a real gap for multi-version claw-code installations. Orchestrators running claw-code in subprocess would benefit immediately. + +**Source.** Jobdori proactive dogfood sweep 2026-04-22 20:58 KST (cycle #24) — ran `claw --help --output-format json` expecting envelope per #178/#179 contract; got text output. Then checked `--version`; not implemented. Filed as natural follow-up to parser-front-door work. Closes the last major discoverability gap. + +**Related prior work.** +- #178 (parse-error envelope): structural contract — unknown commands emit envelope +- #179 (stderr hygiene + real message): quality contract — envelope carries real error message +- #180 (this): discoverability contract — claws can enumerate the surface before dispatching +