mirror of
https://github.com/ultraworkers/claw-code.git
synced 2026-04-24 21:28:11 +08:00
1032 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
YeonGyu-Kim
|
35fee5ecde | roadmap: #160 investigation update — verb classification table needed for clean fix | ||
|
YeonGyu-Kim
|
f034b01733 | roadmap: #160 filed — resume with positional args falls through to Prompt dispatch (#251 family) | ||
|
YeonGyu-Kim
|
c4054d2fa3 | roadmap: principle — backlog truthfulness is execution speed (from #60 framing) | ||
|
YeonGyu-Kim
|
7bd91096a8 | roadmap: #136 + #153b marked CLOSED — compact+json already correct, PATH docs comprehensive | ||
|
YeonGyu-Kim
|
196fe6b493 | roadmap: #136 marked CLOSED — compact+json dispatch already correct | ||
|
YeonGyu-Kim
|
dc8b275c9f | roadmap: principle — cycle cadence (hygiene cycles are first-class, from #59 framing) | ||
|
YeonGyu-Kim
|
8f4f215e27 | roadmap: diagnostic-strictness audit checklist (from cycles #57-#58) | ||
|
YeonGyu-Kim
|
0aa0d3f7cf |
fix(#122b): claw doctor warns when cwd is broad path (home/root)
## What Was Broken
`claw doctor` reported "Status: ok" when run from ~/ or /, but `claw
prompt` in the same directory would error out with:
error: claw is running from a very broad directory (/Users/yeongyu).
The agent can read and search everything under this path.
Diagnostic deception: doctor said green, prompt said red. User runs
doctor to check their setup, sees all green, runs prompt, gets blocked.
Trust in doctor erodes.
This is the exact pattern captured in the 'Diagnostic Commands Must Be
At Least As Strict As Runtime Commands' principle recorded in ROADMAP.md
at cycle #57.
## Root Cause
Two code paths perform the broad-cwd check:
- CliAction::Prompt handler → `enforce_broad_cwd_policy()` (errors out)
- CliAction::Repl handler → same function
But render_doctor_report() never called detect_broad_cwd(). The workspace
health check only looked at whether cwd was inside a git project, not
whether cwd was a dangerously broad path.
## What This Fix Does
Extend `check_workspace_health()` to also probe `detect_broad_cwd()`:
let broad_cwd = detect_broad_cwd();
let (level, summary) = match (in_repo, &broad_cwd) {
(_, Some(path)) => (
DiagnosticLevel::Warn,
format!(
"current directory is a broad path ({}); Prompt/REPL will \
refuse to run here without --allow-broad-cwd",
path.display()
),
),
(true, None) => (DiagnosticLevel::Ok, "project root detected"),
(false, None) => (DiagnosticLevel::Warn, "not inside a git project"),
};
The check now warns about BOTH failure modes with clear messaging about
what Prompt/REPL will do.
## Dogfood Verification
Before fix:
$ cd ~ && claw doctor
Workspace
Status warn
Summary current directory is not inside a git project
[all green otherwise]
$ echo | claw prompt "test"
error: claw is running from a very broad directory (/Users/yeongyu)...
After fix:
$ cd ~ && claw doctor
Workspace
Status warn
Summary current directory is a broad path (/Users/yeongyu);
Prompt/REPL will refuse to run here without
--allow-broad-cwd
$ cd / && claw doctor
Workspace
Status warn
Summary current directory is a broad path (/); ...
Non-regression:
$ cd /tmp/my-project && claw doctor
Workspace
Status warn
Summary current directory is not inside a git project
(unchanged)
$ cd /path/to/real/git/project && claw doctor
Workspace
Status ok
Summary project root detected on branch main
(unchanged)
## Regression Tests Added
- `workspace_check_in_project_dir_reports_ok` — non-broad + in-project = OK
- `workspace_check_outside_project_reports_warn` — non-broad + not-in-project = Warn with 'not inside git project' summary
- 181 binary tests pass (was 179, added 2)
## Related
- Principle: 'Diagnostic Commands Must Be At Least As Strict As Runtime
Commands' (ROADMAP.md cycle #57)
- Companion to #122 (stale-base preflight in doctor)
- Sibling: next step is probably a full runtime-vs-doctor audit for
other asymmetries (auth, sandbox, plugins, hooks)
|
||
|
YeonGyu-Kim
|
86b98d07e9 | roadmap: principle — diagnostic surfaces must be at least as strict as runtime (from #122 framing) | ||
|
YeonGyu-Kim
|
cb8839e050 | roadmap: cluster closure + defer #155/#156 design questions (config section validation, mcp/agents soft-warning) | ||
|
YeonGyu-Kim
|
41b0006eea | roadmap: cluster closure note — help-parity family complete (#130c, #130d, #130e) | ||
|
YeonGyu-Kim
|
9dd7e79eb2 |
fix(#130e-B): route plugins/prompt --help to dedicated help topics
## What Was Broken (ROADMAP #130e Category B)
Two remaining surface-level help outliers after #130e-A:
$ claw plugins --help
Unknown /plugins action '--help'. Use list, install, enable, disable, uninstall, or update.
$ claw prompt --help
claw v0.1.0 (top-level help — wrong help topic)
`plugins` treated `--help` as an invalid subaction name. `prompt`
was explicitly listed in the early `wants_help` interception with
commit/pr/issue, which routed to top-level help instead of
prompt-specific help.
## Root Cause (Traced)
1. **plugins**: `parse_local_help_action()` didn't have a "plugins"
arm, so `["plugins", "--help"]` returned None and continued into
the `"plugins"` parser arm (main.rs:1031), which treated `--help`
as the `action` argument. Runtime layer then rejected it as
"Unknown action".
2. **prompt**: At main.rs:~800, there was an early interception for
`--help` following certain subcommands (prompt, commit, pr, issue)
that forced `wants_help = true`, routing to generic top-level help
instead of letting parse_local_help_action produce a prompt-specific
topic.
## What This Fix Does
Same pattern as #130c/#130d/#130e-A:
1. **LocalHelpTopic enum extended** with Plugins, Prompt variants
2. **parse_local_help_action() extended** to map both new cases
3. **Help topic renderers added** with accurate usage info
4. **Early prompt-interception removed** — prompt now falls through to
parse_local_help_action like other subcommands. commit/pr/issue
(which aren't actual subcommands yet) remain in the early list.
## Dogfood Verification
Before fix:
$ claw plugins --help
Unknown /plugins action '--help'. Use list, install, enable, ...
$ claw prompt --help
claw v0.1.0
(top-level help, not prompt-specific)
After fix:
$ claw plugins --help
Plugins
Usage claw plugins [list|install|enable|disable|uninstall|update] [<target>]
Purpose manage bundled and user plugins from the CLI surface
...
$ claw prompt --help
Prompt
Usage claw prompt <prompt-text>
Purpose run a single-turn, non-interactive prompt and exit
Flags --model · --allowedTools · --output-format · --compact
...
## Non-Regression Verification
- `claw plugins` (no args) → still displays plugin inventory ✅
- `claw plugins list` → still works correctly ✅
- `claw prompt "text"` → still requires credentials, runs prompt ✅
- All 180 binary tests pass ✅
- All 466 library tests pass ✅
## Regression Tests Added (4+ assertions)
- `plugins --help` → HelpTopic(Plugins)
- `prompt --help` → HelpTopic(Prompt)
- Short forms `plugins -h` / `prompt -h` both work
- `prompt "hello world"` still routes to Prompt action with correct text
## HELP-PARITY SWEEP COMPLETE
All 22 top-level subcommands now emit proper help topics:
| Command | Status |
|---|---|
| help --help | ✅ #130e-A |
| version --help | ✅ pre-existing |
| status --help | ✅ pre-existing |
| sandbox --help | ✅ pre-existing |
| doctor --help | ✅ pre-existing |
| acp --help | ✅ pre-existing |
| init --help | ✅ pre-existing |
| state --help | ✅ pre-existing |
| export --help | ✅ pre-existing |
| diff --help | ✅ #130c |
| config --help | ✅ #130d |
| mcp --help | ✅ pre-existing |
| agents --help | ✅ pre-existing |
| plugins --help | ✅ #130e-B (this commit) |
| skills --help | ✅ pre-existing |
| submit --help | ✅ #130e-A |
| prompt --help | ✅ #130e-B (this commit) |
| resume --help | ✅ #130e-A |
| system-prompt --help | ✅ pre-existing |
| dump-manifests --help | ✅ pre-existing |
| bootstrap-plan --help | ✅ pre-existing |
Zero outliers. Contract universally enforced.
## Related
- Closes #130e Category B (plugins, prompt surface-parity)
- Completes entire help-parity sweep family (#130c, #130d, #130e)
- Stacks on #130e-A (dispatch-order fixes) on same worktree
|
||
|
YeonGyu-Kim
|
0ca034472b |
fix(#130e-A): route help/submit/resume --help to help topics before credential check
## What Was Broken (ROADMAP #130e, filed cycle #53) Three subcommands leaked `missing_credentials` errors when called with `--help`: $ claw help --help [error-kind: missing_credentials] error: missing Anthropic credentials... $ claw submit --help [error-kind: missing_credentials] error: missing Anthropic credentials... $ claw resume --help [error-kind: missing_credentials] error: missing Anthropic credentials... This is the same dispatch-order bug class as #251 (session verbs). The parser fell through to the credential check before help-flag resolution ran. Critical discoverability gap: users couldn't learn what these commands do without valid credentials. ## Root Cause (Traced) `parse_local_help_action()` (main.rs:1260) is called early in `parse_args()` (main.rs:1002), BEFORE credential check. But the match statement inside only recognized: status, sandbox, doctor, acp, init, state, export, version, system-prompt, dump-manifests, bootstrap-plan, diff, config. `help`, `submit`, `resume` were NOT in the list, so the function returned `None`, and parsing continued to credential check which then failed. ## What This Fix Does Same pattern as #130c (diff) and #130d (config): 1. **LocalHelpTopic enum extended** with Meta, Submit, Resume variants 2. **parse_local_help_action() extended** to map the three new cases 3. **Help topic renderers added** with accurate usage info Three-line change to parse_local_help_action: "help" => LocalHelpTopic::Meta, "submit" => LocalHelpTopic::Submit, "resume" => LocalHelpTopic::Resume, Dispatch order (parse_args): 1. --resume parsing 2. parse_local_help_action() ← NOW catches help/submit/resume --help 3. parse_single_word_command_alias() 4. parse_subcommand() ← Credential check happens here ## Dogfood Verification Before fix (all three): $ claw help --help [error-kind: missing_credentials] error: missing Anthropic credentials... After fix: $ claw help --help Help Usage claw help [--output-format <format>] Purpose show the full CLI help text (all subcommands, flags, environment) ... $ claw submit --help Submit Usage claw submit [--session <id|latest>] <prompt-text> Purpose send a prompt to an existing managed session Requires valid Anthropic credentials (when actually submitting) ... $ claw resume --help Resume Usage claw resume [<session-id|latest>] Purpose restart an interactive REPL attached to a managed session ... ## Non-Regression Verification - `claw help` (no --help) → still shows full CLI help ✅ - `claw submit "text"` (with prompt) → still requires credentials ✅ - `claw resume` (bare) → still emits slash command guidance ✅ - All 180 binary tests pass ✅ - All 466 library tests pass ✅ ## Regression Tests Added (6 assertions) - `help --help` → routes to HelpTopic(Meta) - `submit --help` → routes to HelpTopic(Submit) - `resume --help` → routes to HelpTopic(Resume) - Short forms: `help -h`, `submit -h`, `resume -h` all work ## Pattern Note This is Category A of #130e (dispatch-order bugs). Same class as #251. Category B (surface-parity: plugins, prompt) will be handled in a follow-up commit/branch. ## Help-Parity Sweep Status After cycle #52 (#130c diff, #130d config), help sweep revealed: | Command | Before | After This Commit | |---|---|---| | help --help | missing_credentials | ✅ Meta help | | submit --help | missing_credentials | ✅ Submit help | | resume --help | missing_credentials | ✅ Resume help | | plugins --help | "Unknown action" | ⏳ #130e-B (next) | | prompt --help | wrong help | ⏳ #130e-B (next) | ## Related - Closes #130e Category A (dispatch-order help fixes) - Same bug class as #251 (session verbs) - Stacks on #130d (config help) on same worktree branch - #130e Category B (plugins, prompt) queued for follow-up |
||
|
YeonGyu-Kim
|
762e9bb212 | roadmap: file #130e — help-parity sweep reveals 5 additional anomalies (3 dispatch-order, 2 surface) | ||
|
YeonGyu-Kim
|
19638a015e |
fix(#130d): accept --help / -h in claw config arm, route to help topic
## What Was Broken (ROADMAP #130d, filed cycle #52) `claw config --help` was silently ignored — the command executed and displayed the config dump instead of showing help: $ claw config --help Config Working directory /private/tmp/dogfood-probe-47 Loaded files 0 Merged keys 0 (displays full config, not help) Expected: help for the config command. Actual: silent acceptance of `--help`, runs config display anyway. This is the opposite outlier from #130c (which rejected help with an error). Together they form the help-parity anomaly: - #130c `diff --help` → error (rejects help) - #130d `config --help` → silent ignore (runs command, ignores help) - Others (status, mcp, export) → proper help - Expected behavior: all commands should show help on `--help` ## Root Cause (Traced) At main.rs:1050, the `"config"` parser arm parsed arguments positionally: "config" => { let tail = &rest[1..]; let section = tail.first().cloned(); // ... ignores unrecognized args like --help silently Ok(CliAction::Config { section, ... }) } Unlike the `diff` arm (#130c), `config` had no explicit check for extra args. It positionally parsed the first arg as an optional `section` and silently accepted/ignored any trailing arg, including `--help`. ## What This Fix Does Same pattern as #130c (help-surface parity): 1. **LocalHelpTopic enum extended** with new `Config` variant 2. **parse_local_help_action() extended** to map `"config"` → `LocalHelpTopic::Config` 3. **config arm guard added**: check for help flag before parsing section 4. **Help topic renderer added**: human-readable help text for config Fix locus at main.rs:1050: "config" => { // #130d: accept --help / -h and route to help topic if rest.len() >= 2 && is_help_flag(&rest[1]) { return Ok(CliAction::HelpTopic(LocalHelpTopic::Config)); } let tail = &rest[1..]; // ... existing parsing continues } ## Dogfood Verification Before fix: $ claw config --help Config Working directory ... Loaded files 0 (no help, runs config) After fix: $ claw config --help Config Usage claw config [--cwd <path>] [--output-format <format>] Purpose merge and display the resolved configuration Options --cwd overrides the workspace directory Output loaded files and merged key-value pairs Formats text (default), json Related claw status · claw doctor · claw init Short form `claw config -h` also works. ## Non-Regression Verification - `claw config` (no args) → still displays config dump ✅ - `claw config permissions` (section arg) → still works ✅ - All 180 binary tests pass ✅ - All 466 library tests pass ✅ ## Regression Tests Added (4 assertions) - `config --help` → routes to `HelpTopic(LocalHelpTopic::Config)` - `config -h` (short form) → routes to help topic - bare `config` (no args) → still routes to `Config` action - `config permissions` (with section) → still works correctly ## Pattern Note #130c and #130d form a pair: two outlier failure modes in help handling for local introspection commands: - #130c `diff` rejected help (loud error) → fixed with guard + routing - #130d `config` silently ignored help (silent accept) → fixed with same pattern Both are now consistent with the rest of the CLI (status, mcp, export, etc.). ## Related - Closes #130d (config help discoverability gap) - Completes help-parity family (#130c, #130d) - Stacks on #130c (diff help fix) on same worktree branch - Part of help-consistency thread (#141 audit) |
||
|
YeonGyu-Kim
|
5e29430d4f | roadmap: file #130d — config command silently ignores --help, displays config dump instead | ||
|
YeonGyu-Kim
|
83f744adf0 |
fix(#130c): accept --help / -h in claw diff arm
## What Was Broken (ROADMAP #130c, filed cycle #50) `claw diff --help` was rejected with: [error-kind: unknown] error: unexpected extra arguments after `claw diff`: --help Other local introspection commands accept --help fine: - `claw status --help` → shows help ✅ - `claw mcp --help` → shows help ✅ - `claw export --help` → shows help ✅ - `claw diff --help` → error ❌ (outlier) This is a help-surface parity bug: `diff` is the only local command that rejects --help as "extra arguments" before the help detector gets a chance to run. ## Root Cause (Traced) At main.rs:1063, the `"diff"` parser arm rejected ALL extra args: "diff" => { if rest.len() > 1 { return Err(format!("unexpected extra arguments after `claw diff`: {}", ...)); } Ok(CliAction::Diff { output_format }) } When parsing `["diff", "--help"]`, `rest.len() > 1` was true (length is 2) and `--help` was rejected as extra argument. Other commands (status, sandbox, doctor, init, state, export, etc.) routed through `parse_local_help_action()` which detected `--help` / `-h` and routed to a LocalHelpTopic. The `diff` arm lacked this guard. ## What This Fix Does Three minimal changes: 1. **LocalHelpTopic enum extended** with new `Diff` variant 2. **parse_local_help_action() extended** to map `"diff"` → `LocalHelpTopic::Diff` 3. **diff arm guard added**: check for help flag before extra-args validation 4. **Help topic renderer added**: human-readable help text for diff command Fix locus at main.rs:1063: "diff" => { // #130c: accept --help / -h as first argument and route to help topic if rest.len() == 2 && is_help_flag(&rest[1]) { return Ok(CliAction::HelpTopic(LocalHelpTopic::Diff)); } if rest.len() > 1 { /* existing error */ } Ok(CliAction::Diff { output_format }) } ## Dogfood Verification Before fix: $ claw diff --help [error-kind: unknown] error: unexpected extra arguments after `claw diff`: --help After fix: $ claw diff --help Diff Usage claw diff [--output-format <format>] Purpose show local git staged + unstaged changes Requires workspace must be inside a git repository ... And `claw diff -h` (short form) also works. ## Non-Regression Verification - `claw diff` (no args) → still routes to Diff action correctly - `claw diff foo` (unknown arg) → still rejected as "unexpected extra arguments" - `claw diff --output-format json` (valid flag) → still works - All 180 binary tests pass - All 466 library tests pass ## Regression Tests Added (4 assertions) - `diff --help` → routes to HelpTopic(LocalHelpTopic::Diff) - `diff -h` (short form) → routes to HelpTopic(LocalHelpTopic::Diff) - bare `diff` → still routes to Diff action - `diff foo` (unknown arg) → still errors with "extra arguments" ## Pattern Follows #141 help-consistency work (extending LocalHelpTopic to cover more subcommands). Clean surface-parity fix: identify the outlier, add the missing guard. Low-risk, high-clarity. ## Related - Closes #130c (diff help discoverability gap) - Stacks on #130b (filesystem context) and #251 (session dispatch) - Part of help-consistency thread (#141 audit, #145 plugins wiring) |
||
|
YeonGyu-Kim
|
0d8adceb67 | roadmap: file #130c — pure-local commands reject --help as extra argument (diff, config, status) | ||
|
YeonGyu-Kim
|
d49a75cad5 |
fix(#130b): enrich filesystem I/O errors with operation + path context
## What Was Broken (ROADMAP #130b, filed cycle #47) In a fresh workspace, running: claw export latest --output /private/nonexistent/path/file.jsonl --output-format json produced: {"error":"No such file or directory (os error 2)","hint":null,"kind":"unknown","type":"error"} This violates the typed-error contract: - Error message is a raw errno string with zero context - Does not mention the operation that failed (export) - Does not mention the target path - Classifier defaults to "unknown" even though the code path knows this is a filesystem I/O error ## Root Cause (Traced) run_export() at main.rs:~6915 does: fs::write(path, &markdown)?; When this fails: 1. io::Error propagates via ? to main() 2. Converted to string via .to_string() in error handler 3. classify_error_kind() cannot match "os error" or "No such file" 4. Defaults to "kind": "unknown" The information is there at the source (operation name, target path, io::ErrorKind) but lost at the propagation boundary. ## What This Fix Does Three changes: 1. **New helper: contextualize_io_error()** (main.rs:~260) Wraps an io::Error with operation name + target path into a recognizable message format: "{operation} failed: {target} ({error})" 2. **Classifier branch added** (classify_error_kind at main.rs:~270) Recognizes the new format and classifies as "filesystem_io_error": else if message.contains("export failed:") || message.contains("diff failed:") || message.contains("config failed:") { "filesystem_io_error" } 3. **run_export() wired** (main.rs:~6915) fs::write() call now uses .map_err() to enrich io::Error: fs::write(path, &markdown).map_err(|e| -> Box<dyn std::error::Error> { contextualize_io_error("export", &path.display().to_string(), e).into() })?; ## Dogfood Verification Before fix: {"error":"No such file or directory (os error 2)","kind":"unknown","type":"error"} After fix: {"error":"export failed: /private/nonexistent/path/file.jsonl (No such file or directory (os error 2))","kind":"filesystem_io_error","type":"error"} The envelope now tells downstream claws: - WHAT operation failed (export) - WHERE it failed (the path) - WHAT KIND of failure (filesystem_io_error) - The original errno detail preserved for diagnosis ## Non-Regression Verification - Successful export still works (emits "kind": "export" envelope as before) - Session not found error still emits "session_not_found" (not filesystem) - missing_credentials still works correctly - cli_parse still works correctly - All 180 binary tests pass - All 466 library tests pass - All 95 compat-harness tests pass ## Regression Tests Added Inside the main CliAction test function: - "export failed:" pattern classifies as "filesystem_io_error" (not "unknown") - "diff failed:" pattern classifies as "filesystem_io_error" - "config failed:" pattern classifies as "filesystem_io_error" - contextualize_io_error() produces a message containing operation name - contextualize_io_error() produces a message containing target path - Messages produced by contextualize_io_error() are classifier-recognizable ## Scope This is the minimum viable fix: enrich export's fs::write with context. Future work (filed as part of #130b scope): apply same pattern to other filesystem operations (diff, plugins, config fs reads, session store writes, etc.). Each application is a copy-paste of the same helper pattern. ## Pattern Follows #145 (plugins parser interception), #248-249 (arm-level leak templates). Helper + classifier + call site wiring. Minimal diff, maximum observability gain. ## Related - Closes #130b (filesystem error context preservation) - Stacks on top of #251 (dispatch-order fix) — same worktree branch - Ground truth for future #130 broader sweep (other io::Error sites) |
||
|
YeonGyu-Kim
|
9eba71da81 | roadmap: file #153b — PATH setup guide follow-up to #153 | ||
|
YeonGyu-Kim
|
ef5aae3ddd | roadmap: file #130b — filesystem errors lose context, emit generic errno strings (export command case) | ||
|
YeonGyu-Kim
|
f05bc037de |
docs(#250, #251): Align SCHEMAS.md with actual binary, downgrade #250 to scope-reduced
Cycle #46 follow-up to cycle #45's #251 implementation. Closes #250's implementation urgency by aligning docs with reality. SCHEMAS.md Updates: For each of the 4 session-management verbs, added: 1. Status marker (Implemented or Stub only) 2. Actual binary envelope (shape produced by the #251-fixed binary) 3. Aspirational (future) shape (original SCHEMAS.md content, preserved as target) 4. Gap notes where the two diverge Per-verb status: - list-sessions: Implemented, nested field layout - load-session: Implemented, nested session object with local session_not_found error - delete-session: Stub, emits not_yet_implemented (local error, not auth) - flush-transcript: Stub, emits not_yet_implemented (local error, not auth) ROADMAP.md Updates: - #251 marked CLOSED: Full status with commit ref, test counts. - #250 marked SCOPE-REDUCED: Option A resolved by #251, Option C moot, only Option B (doc alignment) remains as future cleanup. Why this matters: Every code change should close its documentation loop. #251 landed on the branch, but SCHEMAS.md still described aspirational shapes without marking which were implemented. Claws reading SCHEMAS.md would have assumed full conformance and hit surprises. Now the document tells the truth about which verbs work, which are stubs, and why. Related: - #251 implementation on feat/jobdori-251-session-dispatch branch - #250 scope-reduced to Option B (field-name harmonization) - #145/#146 parser fall-through fix precedent |
||
|
YeonGyu-Kim
|
dc274a0f96 |
fix(#251): intercept session-management verbs at top-level parser to bypass credential check
## What Was Broken (ROADMAP #251) Session-management verbs (list-sessions, load-session, delete-session, flush-transcript) were falling through to the parser's `_other => Prompt` catchall at main.rs:~1017. This construed them as `CliAction::Prompt { prompt: "list-sessions", ... }` which then required credentials via the Anthropic API path. The result: purely-local session operations emitted `missing_credentials` errors instead of session-layer envelopes. ## Acceptance Criterion The fix's essential requirement (stated by gaebal-gajae): **"These 4 verbs stop falling through to Prompt and emitting `missing_credentials`."** Not "all 4 are fully implemented to spec" — stubs are acceptable for delete-session and flush-transcript as long as they route LOCALLY. ## What This Fix Does Follows the exact pattern from #145 (plugins) and #146 (config/diff): 1. **CliAction enum** (main.rs:~700): Added 4 new variants. 2. **Parser** (main.rs:~945): Added 4 match arms before the `_other => Prompt` catchall. Each arm validates the verb's positional args (e.g., load-session requires a session-id) and rejects extra arguments. 3. **Dispatcher** (main.rs:~455): - list-sessions → dispatches to `runtime::session_control::list_managed_sessions_for()` - load-session → dispatches to `runtime::session_control::load_managed_session_for()` - delete-session → emits `not_yet_implemented` error (local, not auth) - flush-transcript → emits `not_yet_implemented` error (local, not auth) ## Dogfood Verification Run on clean environment (no credentials): ```bash $ env -i PATH=$PATH HOME=$HOME claw list-sessions --output-format json { "command": "list-sessions", "sessions": [ {"id": "session-1775777421902-1", ...}, ... ] } # ✓ Session-layer envelope, not auth error $ env -i PATH=$PATH HOME=$HOME claw load-session nonexistent --output-format json {"error":"session not found: nonexistent", "kind":"session_not_found", ...} # ✓ Local session_not_found error, not missing_credentials $ env -i PATH=$PATH HOME=$HOME claw delete-session test-id --output-format json {"command":"delete-session","error":"not_yet_implemented","kind":"not_yet_implemented","type":"error"} # ✓ Local not_yet_implemented, not auth error $ env -i PATH=$PATH HOME=$HOME claw flush-transcript test-id --output-format json {"command":"flush-transcript","error":"not_yet_implemented","kind":"not_yet_implemented","type":"error"} # ✓ Local not_yet_implemented, not auth error ``` Regression sanity: ```bash $ claw plugins --output-format json # #145 still works $ claw prompt "hello" --output-format json # still requires credentials correctly $ claw list-sessions extra arg --output-format json # rejects extra args with cli_parse ``` ## Regression Tests Added Inside `removed_login_and_logout_subcommands_error_helpfully` test function: - `list-sessions` → CliAction::ListSessions (both text and JSON output) - `load-session <id>` → CliAction::LoadSession with session_reference - `delete-session <id>` → CliAction::DeleteSession with session_id - `flush-transcript <id>` → CliAction::FlushTranscript with session_id - Missing required arg errors (load-session and delete-session without ID) - Extra args rejection (list-sessions with extra positional args) All 180 binary tests pass. 466 library tests pass. ## Fix Scope vs. Full Implementation This fix addresses #251 (dispatch-order bug) and #250's Option A (implement the surfaces). list-sessions and load-session are fully functional via existing runtime::session_control helpers. delete-session and flush-transcript are stubbed with local "not yet implemented" errors to satisfy #251's acceptance criterion without requiring additional session-store mutations that can ship independently in a follow-up. ## Template Exact same pattern as #145 (plugins) and #146 (config/diff): top-level verb interception → CliAction variant → dispatcher with local operation. ## Related Closes #251. Addresses #250 Option A for 4 verbs. Does not block #250 Option B (documentation scope guards) which remains valuable. |
||
|
YeonGyu-Kim
|
2fcb85ce4e |
ROADMAP #251: dispatch-order bug — session-management verbs fall through to Prompt before credential check (filed by gaebal-gajae; formalized by Jobdori cycle #40)
Cycle #40: gaebal-gajae conceived #251 in their 00:00 Discord cycle status but hadn't committed to ROADMAP yet. Jobdori verified their diagnosis with code trace and formalized into ROADMAP with the proper framing relationship to #250. ## What This Pinpoint Says Same observable as #250 (session-management verbs emit missing_credentials instead of SCHEMAS.md envelope) but reframed at the dispatch-order layer: - #250 says: surface missing on canonical binary vs SCHEMAS.md promise - #251 says: top-level parser fall-through happens BEFORE dispatcher could intercept, so credential resolution runs before the verb is classified as a purely-local operation #251's framing is sharper because it identifies WHY the fall-through produces auth errors, not just that it does. ## Verified Code Trace - main.rs:1017-1027 is the _other => Prompt catchall - joins all rest[] tokens into joined, constructs CliAction::Prompt - downstream resolves credentials -> emits missing_credentials - No credential call would be needed had the verb been intercepted Same pattern has been fixed before for other purely-local verbs: - #145: plugins (main.rs:888-906, explicit match arm) - #146: config and diff (main.rs:911-935, same shape) #251 extends this to the 4 session-management verbs. ## Recommended Sequence 1. #251 fix (4 match arms mirroring #145/#146) — principled solution 2. #250's Option B (docs scope note) — guard against future drift 3. #250's Option C (reject with redirect) — unnecessary if #251 lands ## Discipline Per cycle #24 calibration: - Red-state bug? Borderline (silent misroute to auth error class) - Real friction? ✓ (4 documented surfaces emit wrong error class) - Evidence-backed? ✓ (code trace + prior-fix precedent #145/#146) - Same-cycle fix? ✗ (filed + document, boundary discipline #36) - Implementation cost? ~40 lines Rust + tests, bounded ## Credit Conception: gaebal-gajae (Discord msg 1496526112254328902, 00:00 KST) Formalization: Jobdori cycle #40 (code trace + precedent linking) This is the right kind of collaboration: gaebal-gajae saw the dispatch pattern I had missed in #250 (I framed as surface parity; they framed as dispatch order). I verified their diagnosis and committed the ROADMAP entry. Two framings make the pinpoint sharper than either alone. |
||
|
YeonGyu-Kim
|
f1103332d0 |
ROADMAP #130: re-verify still-open on main HEAD 186d42f; add classifier-cluster pairing note
Cycle #39 dogfood re-verification of #130 (filed 2026-04-20). All 5 filesystem failure modes reproduce identically on main HEAD 186d42f, 2 days after original filing. Gap is unchanged. ## What's Added 1. **[STILL OPEN — re-verified 2026-04-22 cycle #39]** marker on the entry so readers can see immediately that the pinpoint hasn't been accidentally closed. 2. Full 5-mode repro output preserved verbatim for the current HEAD, so future re-verifications have a concrete baseline to diff against. 3. **New evidence not in original filing**: the classifier actively chose `kind: "unknown"` rather than just omitting the field. This means classify_error_kind() has NO substring match for "Is a directory", "No such file", "Operation not permitted", or "File exists". The typed-error contract is thus twice-broken on this path. 4. **Pairing with #247/#248/#249 classifier sweep**: the classifier-level part of #130 could land in the same sweep (add substring branches for io::ErrorKind strings). The context-preservation part (fix run_export's bare `?`) is a separate, larger change. ## Why Re-Verification Not Re-Filing Per cycle #24 discipline: speculative re-filings add noise, real confirmations add truth. #130 was already filed with exact repros, code trace, and fix shape. My dogfood hit the same gap on fresh HEAD — the right output is confirming the gap is still there (not filing #251 for the same bug). This is the same pattern as cycle #32's "mark #127 CLOSED" reality-sync: documentation-drift prevention through explicit status markers. ## New Pattern "Reality-sync via re-verification" — re-running a filed pinpoint's repro on fresh HEAD and adding the timestamp + output proves the gap is still real without inventing new filings. Cycle #24 calibration keeps ROADMAP entries honest. Per cycle #24 calibration: - Red-state bug? ⚠️ borderline (errors surfaced, but kind=unknown is demonstrably wrong on a path where the system knows the errno) - Real friction? ✓ (re-verified on fresh HEAD) - Evidence-backed? ✓ (5-mode repro + classifier trace) - Same-cycle fix? ✗ (classifier-level part could join #247/#248/#249 sweep; context-preservation part is larger refactor) - Implementation cost? Classifier part ~10 lines; full context fix ~60 lines Source: Jobdori cycle #39 proactive dogfood in response to Clawhip pinpoint nudge. Probed export filesystem errors; discovered this was #130 reconfirmation, not new bug. Applied reality-sync pattern from cycle #32. |
||
|
YeonGyu-Kim
|
186d42f979 |
ROADMAP #250: CLI surface parity gap — SCHEMAS.md's list-sessions/delete-session/etc. are Python-only; Rust binary falls through to Prompt with cred error
Cycle #38 dogfood finding. Probed session management via the top-level subcommand path documented in SCHEMAS.md; discovered the Rust binary doesn't implement these as top-level subcommands. The literal token 'list-sessions' falls through the _other => Prompt arm and returns 'missing Anthropic credentials' instead of the documented envelope. ## The Gap SCHEMAS.md documents 14 CLAWABLE top-level subcommands. Python audit harness (src/main.py) implements all 14. Rust binary implements ~8 of them as top-level, routing session management through /session slash commands via --resume instead. Repro: $ env -i PATH=$PATH HOME=$HOME claw list-sessions --output-format json {"error":"missing Anthropic credentials; ...","kind":"missing_credentials"} $ claw --resume latest /session list --output-format json {"active":"...","kind":"session_list","sessions":[...]} $ python3 -m src.main list-sessions --output-format json {"command":"list-sessions","sessions":[...],"exit_code":0} Same operation, three different CLI shapes across implementations. ## Classification This is BOTH: - a parser-level trust gap (6th in #108/#117/#119/#122/#127 family; same _other => Prompt fall-through), AND - a cross-implementation parity gap (SCHEMAS.md at repo root doesn't match Rust binary's top-level surface) Unlike prior fall-throughs where the input was malformed, the input here IS a documented surface. The fall-through is wrong for a different reason: the surface exists in the protocol but not in this implementation. ## Three Fix Options Option A: Implement surfaces on Rust binary (highest cost, full parity) Option B: Scope SCHEMAS.md to Python harness (docs-only) Option C: Reject at parse time with redirect hint (cheapest, #127 pattern) Recommended: C first (prevents cred misdirection), then B for docs hygiene, then A if demand justifies. ## Discipline Per cycle #24 calibration: - Red-state bug? ⚠️ borderline — silent misroute to cred error on a documented surface. Not a crash but a real wrong-contract response. - Real friction? ✓ (claws reading SCHEMAS.md hit wrong error on canonical binary) - Evidence-backed? ✓ (dogfood probe + SCHEMAS.md cross-reference + code trace) - Implementation cost? Option C: ~30 lines (bounded). Option A: larger. - Same-cycle fix? ✗ (file + document, defer implementation per #36 boundary discipline) ## Family Position Natural bundle: **#127 + #250** — parser-level fall-through pair with class distinction. #127 fixed suffix-arg-on-valid-verb case. #250 extends to 'entire Python-harness verb treated as prompt.' Same fall-through arm, different entry class. Source: Jobdori cycle #38 proactive dogfood in response to Clawhip pinpoint nudge at msg 1496518474019639408. Probed session management CLI after gaebal-gajae's status sync confirmed no red-state regressions this cycle; found this cross-implementation surface parity gap by comparing SCHEMAS.md claims against actual Rust binary behavior. |
||
|
YeonGyu-Kim
|
5f8d1b92a6 |
ROADMAP #249: resumed-session slash command error envelopes omit kind field
Cycle #37 dogfood finding post-#247 merge. Two Err arms in the resumed-session JSON path at main.rs:2747 and main.rs:2783 emit error envelopes WITHOUT the `kind` field required by the §4.44 typed-envelope contract. ## The Pinpoint Probed resumed-session slash command JSON path: $ claw --output-format json --resume latest /session {"command":"/session","error":"unsupported resumed slash command","type":"error"} # no kind field $ claw --output-format json --resume latest /xyz-unknown {"command":"/xyz-unknown","error":"Unknown slash command: /xyz-unknown\n Help /help lists available slash commands","type":"error"} # no kind field AND multi-line error without split hint Compare to happy path which DOES include kind: $ claw --output-format json --resume latest /session list {"active":"...","kind":"session_list",...} Contract awareness exists. It's just not applied in the Err arms. ## Scope Two atomic fixes in main.rs: - Line 2747: SlashCommand::parse() Err → add kind via classify_error_kind() - Line 2783: run_resume_command() Err → add kind + call split_error_hint() ~15 lines Rust total. Bounded. ## Family Classification §4.44 typed-envelope contract sweep: - #179 (parse-error real message quality) — closed - #181 (envelope exit_code matches process exit) — closed - #247 (classify_error_kind misses prompt-patterns) — closed - #248 (verb-qualified unknown option errors) — in-flight (another agent) - **#249 (resumed-session slash error envelopes omit kind) — filed** Natural bundle #247+#248+#249: classifier/envelope completeness across all three CLI paths (top-level parse, subcommand options, resumed-session slash). ## Discipline Per cycle #24 calibration: - Red-state bug? ✗ (errors surfaced, exit codes correct) - Real friction? ✓ (typed-error contract violation; claws dispatching on error.kind get undefined for all resumed slash-command errors) - Evidence-backed? ✓ (dogfood probe + code trace identified both Err arms) - Implementation cost? ~15 lines (bounded) - Same-cycle fix? ✗ (Rust change, deferred per file-not-fix discipline) ## Not Implementing This Cycle Per the boundary discipline established in cycle #36: I don't touch another agent's in-flight work, and I don't implement a Rust fix same-cycle when the pattern is "file + document + let owner/maintainer decide." Filing with concrete fix shape is the correct output. If demand or red-state symptoms arrive, implementation can follow the same path as #247: file → fix in branch → review → merge. Source: Jobdori cycle #37 proactive dogfood in response to Clawhip pinpoint nudge at msg 1496518474019639408. |
||
|
YeonGyu-Kim
|
84466bbb6c |
fix: #247 classify prompt-related parse errors + unify JSON hint plumbing
Cycle #34 dogfood follow-through on Jobdori cycle #33 pinpoint (#247 filed at fbcbe9d). Closes the two typed-error contract drifts surfaced in that pinpoint against the Rust `claw` binary. ## What was wrong 1. `classify_error_kind()` (main.rs:~251) used substring matching but did NOT match two common prompt-related parse errors: - "prompt subcommand requires a prompt string" - "empty prompt: provide a subcommand..." Both fell through to `"unknown"`. §4.44 typed-error contract specifies `parse | usage | unknown` as distinct classes, so claws dispatching on `error.kind == "cli_parse"` missed those paths entirely. 2. JSON mode dropped the `Run `claw --help` for usage.` hint. Text mode appends it at stderr-print time (main.rs:~234) AFTER split_error_hint() has already serialized the envelope, so JSON consumers never saw it. Text-mode humans got an actionable pointer; machine consumers did not. ## Fix Two small, targeted edits: 1. `classify_error_kind()`: add explicit branches for "prompt subcommand requires" and "empty prompt:" (the latter anchored with `starts_with` so it never hijacks unrelated error messages containing the word). Both route to `cli_parse`. 2. JSON error render path in `main()`: after calling split_error_hint(), if the message carried no embedded hint AND kind is `cli_parse` AND the short-reason does not already embed a `claw --help` pointer, synthesize the same `Run `claw --help` for usage.` trailer that text-mode stderr appends. The embedded-pointer check prevents duplication on the `empty prompt: ... (run `claw --help`)` message which already carries inline guidance. ## Verification Direct repro on the compiled binary: $ claw --output-format json prompt {"error":"prompt subcommand requires a prompt string", "hint":"Run `claw --help` for usage.", "kind":"cli_parse","type":"error"} $ claw --output-format json "" {"error":"empty prompt: provide a subcommand (run `claw --help`) or a non-empty prompt string", "hint":null,"kind":"cli_parse","type":"error"} $ claw --output-format json doctor --foo # regression guard {"error":"unrecognized argument `--foo` for subcommand `doctor`", "hint":"Run `claw --help` for usage.", "kind":"cli_parse","type":"error"} Text mode unchanged in shape; `[error-kind: ...]` prefix now reads `cli_parse` for the two previously-misclassified paths. ## Regression coverage - Unit test `classify_error_kind_covers_prompt_parse_errors_247`: locks both patterns route to `cli_parse` AND that generic "prompt"-containing messages still fall through to `unknown`. - Integration tests in `tests/output_format_contract.rs`: * prompt_subcommand_without_arg_emits_cli_parse_envelope_with_hint_247 * empty_positional_arg_emits_cli_parse_envelope_247 * whitespace_only_positional_arg_emits_cli_parse_envelope_247 * unrecognized_argument_still_classifies_as_cli_parse_247_regression_guard - Full rusty-claude-cli test suite: 218 tests pass (180 bin unit + 15 output_format_contract + 12 resume_slash + 7 compact + 3 mock + 1 cli). ## Family / related Joins §4.44 typed-envelope contract gap family closure: #130, #179, #181, and now **#247**. All four quartet items now have real fixes landed on the canonical binary surface rather than only the Python harness. ROADMAP.md: #247 marked CLOSED with before/after evidence preserved. |
||
|
YeonGyu-Kim
|
fbcbe9d8d5 |
ROADMAP #247: classify_error_kind() misses prompt-related parse errors; hint dropped in JSON envelope
Cycle #33 dogfood finding from direct probe of Rust claw binary: ## The Pinpoint Two related contract drifts in the typed-error envelope: ### 1. Error-kind misclassification `classify_error_kind()` at main.rs:246-280 uses substring matching but does NOT match two common parse error messages: - "prompt subcommand requires a prompt string" → classified as 'unknown' - "empty prompt: provide a subcommand..." → classified as 'unknown' The §4.44 typed-error contract specifies 'parse | usage | unknown' as DISTINCT classes. Known parse errors should be 'cli_parse', not 'unknown'. ### 2. Hint lost in JSON mode Text mode appends 'Run `claw --help` for usage.' to parse errors. JSON mode emits 'hint: null'. The trailer is added at the stderr-print stage AFTER split_error_hint() has already serialized the envelope, so JSON consumers never see it. ## Repro Dogfooded on main HEAD dd0993c (cycle #33): $ claw --output-format json prompt {"error":"prompt subcommand requires a prompt string","hint":null,"kind":"unknown","type":"error"} Expected: kind="cli_parse" + hint="Run \\`claw --help\\` for usage." ## Impact - Claws dispatching on typed error.kind fall back to substring matching - JSON consumers lose actionable hint that text-mode users see - Joins JSON envelope field-quality family (#90, #91, #92, #110, #115, #116, #130, #179, #181, #247) ## Fix Shape 1. Add prompt-pattern clauses to classify_error_kind() (~4 lines) 2. Move hint plumbing to BEFORE JSON envelope serialization (~15 lines) 3. Add golden-fixture regression tests per cycle #30 pattern Not a red-state bug (error IS surfaced, exit code IS correct), but real contract drift. Deferred for implementation; filed per Clawhip nudge to 'add one concrete follow-up to ROADMAP.md'. Per cycle #24 calibration: - Red-state bug? ✗ (errors exit 1 correctly) - Real friction? ✓ (typed-error contract drift) - Evidence-backed? ✓ (dogfood probe + code trace identified both leaks) - Implementation cost? ~20 lines Rust (bounded) - Demand signal needed? Medium — any claw doing error.kind dispatch on prompt-path errors is affected Source: Jobdori cycle #33 direct dogfood 2026-04-22 22:30 KST in response to Clawhip pinpoint nudge at msg 1496503374621970583. |
||
|
YeonGyu-Kim
|
dd0993c157 |
docs: cycle #32 — mark #127 CLOSED; document in-flight branch obsolescence
Cycle #32 dogfood finding: #127 was fixed on main via `a3270db` + `79352a2` (2026-04-20), but the ROADMAP.md entry still lacked a [CLOSED] marker. The in-flight branches `feat/jobdori-127-clean` and `feat/jobdori-127-verb-suffix-flags` were superseded and are now obsolete. ## What This Fixes **Documentation drift:** Pinpoint #127 was complete in code but unmarked in ROADMAP. New contributors checking the roadmap would see it as open work, potentially duplicating effort. **Stale branches:** Two branches (`feat/jobdori-127-clean`, `feat/jobdori-127-verb-suffix-flags`) contain the fix attempt bundled with an unrelated large-scope refactor (5365 lines removed from ROADMAP.md, root-level governance docs deleted, command infra refactored). Their fix was superseded; branches are functionally obsolete. ## Verification Re-verified all 4 #127 scenarios pass on main HEAD `b903e16`: $ claw doctor --json → rejected with "did you mean" hint $ claw doctor garbage → rejected $ claw doctor --unknown-flag → rejected $ claw doctor --output-format json → works (canonical form) All behavior matches #127 acceptance criteria. ## Cluster Impact Post-closure: **parser-level trust gap quintet (#108 + #117 + #119 + #122 + #127) is 5/5 closed**. The `_other => Prompt` fall-through audit is complete. ## Discipline Check Per cycle #24 calibration: - Red-state bug? ✗ (behavior is correct on main) - Real friction? ✓ (ROADMAP drift; obsolete branches adrift) - Evidence-backed? ✓ (dogfood probe confirmed closure; git log confirmed supersession; branch diff confirmed scope contamination) ## Relationship to Gaebal-gajae's Option A Guidance Cycle #32 started by proposing separating the #127 fix from the attached refactor. On deeper probe, discovered the fix was already superseded on main via different commits. Option A (separate the fix) is retroactively satisfied: the fix landed cleanly, the refactor never did. The remaining action is governance hygiene: mark closure, document supersession, flag obsolete branches for deletion. ## Next Actions (not in this commit) - Delete `feat/jobdori-127-clean` locally and on fork (after confirmation) - Delete `feat/jobdori-127-verb-suffix-flags` locally and on fork - Monitor whether any attached refactor content should be re-proposed in its own scoped PR Source: Jobdori cycle #32 dogfood in response to Clawhip 10-min nudge. Proposed Option A (separate fix from refactor); probe revealed the fix already landed via a different commit path, rendering the refactor-only branch obsolete. |
||
|
YeonGyu-Kim
|
b903e1605f |
test: cycle #30 — lock OPT_OUT surface rejection (close parity test gap)
Cycle #30 dogfood found a testing gap: OPT_OUT surfaces were classified in code but their REJECTION behavior was never regression-tested. ## The Gap OPT_OUT_AUDIT.md declares 12 surfaces as intentionally exempt from --output-format. The test suite had: - ✅ test_clawable_surface_has_output_format (CLAWABLE must accept) - ✅ test_every_registered_command_is_classified (no orphans) - ❌ Nothing verifying OPT_OUT surfaces REJECT --output-format If a developer accidentally added --output-format to 'summary' (one of the 12 OPT_OUT surfaces), no test would catch the silent promotion. The classification was governed, but the rejection behavior was NOT. ## What Changed Added TestOptOutSurfaceRejection to test_cli_parity_audit.py with 14 tests: 1. **12 parametrized tests** — one per OPT_OUT surface, verifying each rejects --output-format with an argparse error. 2. **test_opt_out_set_matches_audit_document** — verifies OPT_OUT_SURFACES constant matches the declared 12 surfaces in OPT_OUT_AUDIT.md. 3. **test_opt_out_count_matches_declared** — sanity check that the count stays at 12 as documented. ## Symmetry Achieved Before: only CLAWABLE acceptance tested CLAWABLE accepts --output-format ✅ OPT_OUT behavior: untested After: full parity coverage CLAWABLE accepts --output-format ✅ OPT_OUT rejects --output-format ✅ Audit doc ↔ constant kept in sync ✅ This completes the parity enforcement loop: every new surface is explicitly IN or OUT, and BOTH directions are regression-locked. ## Promotion Path Preserved When a real OPT_OUT surface gains genuine demand (per OPT_OUT_DEMAND_LOG.md): 1. Move from OPT_OUT_SURFACES to CLAWABLE_SURFACES 2. Update OPT_OUT_AUDIT.md with promotion rationale 3. Remove from this test's expected rejections 4. Tests pass (rejection test no longer runs; acceptance test now required) Graceful promotion; no accidental drift. ## Test Count - 222 → 236 passing (+14, zero regressions) - 12 parametrized + 2 metadata = 14 new tests ## Discipline Check Per cycle #24 calibration: - Red-state bug? ✗ (no broken behavior) - Real friction? ✓ (testing gap discovered by dogfood) - Evidence-backed? ✓ (systematic probe revealed missing coverage) This is the cycle #27 taxonomy (structural / quality / cross-channel / text-vs-JSON divergence) extending into classification: not just 'is the envelope right?' but 'is the OPPOSITE-OF-envelope right?' Future cycles can apply the same principle to other classifications: every governed non-goal deserves regression tests that lock its non-goal-ness. Classification: - Real friction: ✓ (cycle #30 dogfood) - Evidence-backed: ✓ (gap discovered by systematic surface audit) - Same-cycle fix: ✓ (maintainership discipline) Source: Jobdori cycle #30 proactive dogfood — probed all 26 subcommands with --output-format json and noticed OPT_OUT rejection pattern was unverified by any dedicated test. |
||
|
YeonGyu-Kim
|
de368a2615 |
docs+test: cycle #29 — document + lock text-mode vs JSON-mode exit divergence
Cycle #29 dogfood found a real pinpoint: cross-mode exit code divergence. ## The Pinpoint Dogfooding the CLI revealed that unknown subcommand errors return different exit codes depending on output mode: $ python3 -m src.main nonexistent-cmd # exit 2 $ python3 -m src.main nonexistent-cmd --output-format json # exit 1 ERROR_HANDLING.md documented the exit-code contract (1=parse, 2=timeout) but did NOT explicitly state the contract applies only to JSON mode. Text mode follows argparse defaults (exit 2 for any parse error), which violates the documented contract when interpreted generally. A claw using text mode with 'claw nonexistent' would see exit 2 and misclassify as timeout per the docs. Real protocol contract gap, not implementation bug. ## Classification This is a DOCUMENTATION gap, not a behavior bug: - Text mode follows argparse convention (reasonable for humans) - JSON mode normalizes to documented contract (reasonable for claws) - The divergence is intentional; only the docs were silent about it Fix = document the divergence explicitly + lock it with tests. NOT fix = change text mode exit code to 1 (would break argparse conventions and confuse human users). ## Documentation Changes ERROR_HANDLING.md: 1. Added IMPORTANT callout in Quick Reference section: 'The exit code contract applies ONLY when --output-format json is explicitly set. Text mode follows argparse conventions.' 2. New 'Text mode vs JSON mode exit codes' table showing exact divergence: - Unknown subcommand: text=2, json=1 - Missing required arg: text=2, json=1 - Session not found: text=1, json=1 (app-level, identical) - Success: text=0, json=0 (identical) - Timeout: text=2, json=2 (identical, #161) 3. Practical rule: 'always pass --output-format json' ## Tests Added (5) TestTextVsJsonModeDivergence in test_cross_channel_consistency.py: 1. test_unknown_command_text_mode_exits_2 — text mode argparse default 2. test_unknown_command_json_mode_exits_1 — JSON mode contract normalized 3. test_missing_required_arg_text_mode_exits_2 — same for missing args 4. test_missing_required_arg_json_mode_exits_1 — same normalization 5. test_success_path_identical_in_both_modes — success exit identical These tests LOCK the expected divergence so: - Documentation stays aligned with implementation - Future changes (either direction) are caught as intentional - Claws trust the docs ## Test Status - 217 → 222 tests passing (+5) - Zero regressions ## Discipline This cycle follows the cycle #28 template exactly: - Dogfood probe revealed real friction (test said exit=2, docs said exit=1) - Minimal fix shape (documentation clarification, not code change) - Regression guard via tests - Evidence-backed, not speculative Relationship to #181: - #181 fixed env.exit_code != process exit (WITHIN JSON mode) - #29 clarifies exit code contract scope (ONLY JSON mode) - Both establish: exit codes are deterministic, but only when --output-format json --- Classification (per cycle #24 calibration): - Red-state bug? ✗ (behavior was reasonable, docs were incomplete) - Real friction? ✓ (docs/code divergence revealed by dogfood) - Evidence-backed? ✓ (test suite probed both modes, found the gap) Source: Jobdori cycle #29 proactive dogfood — in response to Clawhip nudge for pinpoint hunting. Found that text-mode errors return exit 2 but ERROR_HANDLING.md implied exit 1 was the parse-error contract universally. |
||
|
YeonGyu-Kim
|
af306d489e |
feat: #180 implement --version flag for metadata protocol (#28 proactive demand)
Cycle #28 closes the low-hanging metadata protocol gap identified in #180. ## The Gap Pinpoint #180 (filed cycle #24) documented a metadata protocol gap: - `--help` works (argparse default) - `--version` does NOT exist The ROADMAP entry deferred implementation pending demand. Cycle #28 dogfood probe found this during routine invariant audit (attempt to call `--version` as part of comprehensive CLI surface coverage). This is concrete evidence of real friction, not speculative gap-filling. ## Implementation Added `--version` flag to argparse in `build_parser()`: ```python parser.add_argument('--version', action='version', version='claw-code 1.0.0 (Python harness)') ``` Simple one-liner. Follows Python argparse conventions (built-in action='version'). ## Tests Added (3) TestMetadataFlags in test_exec_route_bootstrap_output_format.py: 1. test_version_flag_returns_version_text — `claw --version` prints version 2. test_help_flag_returns_help_text — `claw --help` still works 3. test_help_still_works_after_version_added — Both -h and --help work Regression guard on the original help surface. ## Test Status - 214 → 217 tests passing (+3) - Zero regressions - Full suite green ## Discipline This cycle exemplifies the cycle #24 calibration: - #180 was filed as 'deferred pending demand' - Cycle #28 dogfood found actual friction (proactive test coverage gap) - Evidence = concrete ('--version not found during invariant audit') - Action = minimal implementation + regression tests - No speculation, no feature creep, no implementation before evidence Not 'we imagined someone might want this.' Instead: 'we tried to call it during routine maintenance, got ENOENT, fixed it.' ## Related - #180 (cycle #24): Metadata protocol gap filed - Cycle #27: Cross-channel consistency audit established framework - Cycle #28 invariant audit: Discovered actual friction, triggered fix --- Classification (per cycle #24 calibration): - Red-state bug? ✗ (not a malfunction, just an absence) - Real friction? ✓ (audit probe could not call the flag, had to special-case) - Evidence-backed? ✓ (proactive test coverage revealed the gap) Source: Jobdori cycle #28 dogfood — invariant audit attempting comprehensive CLI surface coverage found that --version was unsupported. |
||
|
YeonGyu-Kim
|
fef249d9e7 |
test: cycle #27 — cross-channel consistency audit suite
Cycle #27 ships a new test class systematizing the three-layer protocol invariant framework. ## Context After cycles #20–#26, the protocol has three distinct invariant classes: 1. **Structural compliance** (#178): Does the envelope exist? 2. **Quality compliance** (#179): Is stderr silent + error message truthful? 3. **Cross-channel consistency** (#181 + NEW): Do multiple channels agree? #181 revealed a critical gap: the second test class was incomplete. Envelopes could be structurally valid, quality-compliant, but still lie about their own state (envelope.exit_code != actual exit). ## New Test Class TestCrossChannelConsistency in test_cross_channel_consistency.py captures the third invariant layer with 5 dedicated tests: 1. envelope.command ↔ dispatched subcommand 2. envelope.output_format ↔ --output-format flag 3. envelope.timestamp ↔ actual wall clock (recent, <5s) 4. envelope.exit_code ↔ process exit code (cycle #26/#181 regression guard) 5. envelope boolean fields (found/handled/deleted) ↔ error block presence Each test specifically targets cross-channel truth, not structure or quality. ## Why Separate Test Classes Matter A command can fail all three ways independently: | Failure mode | Exit/Crash | Test class | Example | |---|---|---|---| | Structural | stderr noise | TestParseErrorEnvelope | argparse leaks to stderr | | Quality | correct shape, wrong message | TestParseErrorStderrHygiene | error instead of real message | | Cross-channel | truthy field, lie about state | TestCrossChannelConsistency | exit_code: 0 but exit 1 | #181 was invisible to the first two classes. A claw passing all structure/ quality tests could still be misled. The third class catches that. ## Audit Results (Cycle #27) All 5 tests pass — no drift detected in any channel pair: - ✅ Envelope command always matches dispatch - ✅ Envelope output_format always matches flag - ✅ Envelope timestamp always recent (<5s) - ✅ Envelope exit_code always matches process exit (post-#181 guard) - ✅ Boolean fields consistent with error block presence The systematic audit proved the fix from #181 holds, and identified no new cross-channel gaps. ## Test Impact - 209 → 214 tests passing (+5) - Zero regressions - New invariant class now has dedicated test suite - Future cross-channel bugs will be caught by this class ## Related - #178 (#20): Parser-front-door structural contract - #179 (#20): Stderr hygiene + real error message quality - #181 (#26): Envelope exit_code must match process exit - #182-N: Future cross-channel contract violations will be caught by TestCrossChannelConsistency This test class is evergreen — as new fields/channels are added to the protocol, invariants for those channels should be added here, not mixed with other test classes. Keeping invariant classes separate makes regression attribution instant (e.g., 'TestCrossChannelConsistency failed' = 'some truth channel disagreed'). Classification (per cycle #24 calibration): - Red-state bug: ✗ (audit is green) - Real friction: ✓ (structured audit of documented invariants) - Proof of equilibrium: ✓ (systematic verification, no gaps found) Source: Jobdori cycle #27 proactive invariant audit — following gaebal guidance to probe documented invariants, not speculative gaps. |
||
|
YeonGyu-Kim
|
7724bf98fd |
fix: #181 — envelope exit_code must match process exit code (exec-command/exec-tool)
Cycle #26 dogfood found a real red-state bug in the JSON envelope contract. ## The Bug exec-command and exec-tool not-found cases return exit code 1 from the process, but the envelope reports exit_code: 0 (the default from wrap_json_envelope). This is a protocol violation. Repro (before fix): $ claw exec-command unknown-cmd test --output-format json > out.json $ echo $? 1 $ jq '.exit_code' out.json 0 # WRONG — envelope lies about exit code Claws reading the envelope's exit_code field get misinformation. A claw implementing the canonical ERROR_HANDLING.md pattern (check exit_code, then classify by error.kind) would incorrectly treat failures as successes when dispatching on the envelope alone. ## Root Cause main.py lines 687–739 (exec-command + exec-tool handlers): - Return statement: 'return 0 if result.handled else 1' (correct) - Envelope wrap: 'wrap_json_envelope(envelope, args.command)' (uses default exit_code=0, IGNORES the return value) The envelope wrap was called BEFORE the return value was computed, so the exit_code field was never synchronized with the actual exit code. ## The Fix Compute exit_code ONCE at the top: exit_code = 0 if result.handled else 1 Pass it explicitly to wrap_json_envelope: wrap_json_envelope(envelope, args.command, exit_code=exit_code) Return the same value: return exit_code This ensures the envelope's exit_code field is always truth — the SAME value the process returns. ## Tests Added (3) TestEnvelopeExitCodeMatchesProcessExit in test_exec_route_bootstrap_output_format.py: 1. test_exec_command_not_found_envelope_exit_matches: Verifies exec-command unknown-cmd returns exit 1 in both envelope and process. 2. test_exec_tool_not_found_envelope_exit_matches: Same for exec-tool. 3. test_all_commands_exit_code_invariant: Audit across 4 known non-zero cases (show-command, show-tool, exec-command, exec-tool not-found). Guards against the same bug in other surfaces. ## Impact - 206 → 209 passing tests (+3) - Zero regressions - Protocol contract now truthful: envelope.exit_code == process exit - Claws using the one-handler pattern from ERROR_HANDLING.md now get correct information ## Related - ERROR_HANDLING.md (cycle #22): Documented exit_code as machine-readable contract field - #178/#179 (cycles #19/#20): Closed parser-front-door contract - This closes a gap in the WORK PROTOCOL contract — envelope values must match reality, not just be structurally present. Classification (per cycle #24 calibration): - Red-state bug: ✓ (contract violation, claws get misinformation) - Real friction: ✓ (discovered via dogfood, not speculative) - Fix ships same-cycle: ✓ (discipline per maintainership mode) Source: Jobdori cycle #26 dogfood — ran multiple edge-case probes, noticed exec-command envelope showed exit_code: 0 while process exited 1. Investigated wrap_json_envelope default behavior, confirmed bug, fixed and tested in same cycle. |
||
|
YeonGyu-Kim
|
70b2f6a66f |
docs: USAGE.md — cross-link ERROR_HANDLING.md for subprocess orchestration
Cycle #25 ships navigation improvements connecting USAGE (setup/interactive) to ERROR_HANDLING.md (subprocess/orchestration patterns). Before: USAGE.md had JSON scripting mention but no link to error-handling guide. New users reading USAGE would see JSON is available, but wouldn't discover the error-handling pattern without accidentally finding ERROR_HANDLING.md. After: Two strategic cross-links: 1. Top-level tip box: "Building orchestration code? See ERROR_HANDLING.md" 2. JSON scripting section expanded with examples + link to unified pattern Changes to USAGE.md: - Added TIP callout near top linking to ERROR_HANDLING.md - Expanded "JSON output for scripting" section: - Explains what the envelope contains (exit_code, command, timestamp, fields) - Added 3 command examples (prompt, load-session, turn-loop) - Added callout for dispatchers/orchestrators pointing to ERROR_HANDLING pattern Impact: Operators reading USAGE for "how do I call claw from scripts?" now immediately see the canonical answer (ERROR_HANDLING.md) instead of having to reverse-engineer it from code examples. No code changes. Pure navigation/documentation. Continues the documentation-governance pattern: the work protocol (14 clawable commands) has a consumption guide (ERROR_HANDLING.md), and that guide is now reachable from the main entry point (USAGE.md + README.md top nav). |
||
|
YeonGyu-Kim
|
1d155e4304 |
docs: ROADMAP.md — file #180 (discoverability gap: --help/--version outside JSON contract)
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. |
||
|
YeonGyu-Kim
|
0b5dffb9da |
docs: README.md — promote ERROR_HANDLING.md to first-class navigation
Cycle #23 ships a documentation discoverability fix. After #22 shipping ERROR_HANDLING.md, the next natural step is making it discoverable from the project's entry point (README.md). Before: README top navigation linked to USAGE, PARITY, ROADMAP, Rust workspace. ERROR_HANDLING.md was buried in CLAUDE.md references. After: ERROR_HANDLING.md is now in the top navigation (right after USAGE, before Rust workspace). Also added SCHEMAS.md mention in repository shape. This signals that: 1. Error handling is a first-class concern (not an afterthought) 2. The Python harness documentation (SCHEMAS.md, ERROR_HANDLING.md, CLAUDE.md) is part of the official docs, not just dogfood artifacts 3. New users/claws can discover the error-handling pattern at entry point Impact: Operators building orchestration code will immediately see 'Error Handling' link in navigation, shortening the path to understanding how to consume the protocol reliably. No code changes. No test changes. Pure navigation/discoverability. |
||
|
YeonGyu-Kim
|
932710a626 |
docs: ERROR_HANDLING.md — unified error handler pattern for orchestration code
Cycle #22 ships documentation that operationalizes cycles #178–#179. Problem context: After #178 (parse-error envelope) and #179 (stderr hygiene + real error message), claws can now build a unified error handler for all 14 clawable commands. But there was no guide on how to actually do that. Operators had the pieces; they didn't have the pattern. This file changes that. New file: ERROR_HANDLING.md - Quick reference: exit codes + envelope shapes (0=success, 1=error, 2=timeout) - One-handler pattern: ~80 lines of Python showing how to parse error.kind, check retryable, and decide recovery strategy - Four practical recovery patterns: - Retry on transient errors (filesystem, timeout) - Reuse session after timeout (if cancel_observed=true) - Validate command syntax before dispatch (dry-run --help) - Log errors for observability - Error kinds enumeration (parse, session_not_found, filesystem, runtime, timeout) - Common mistakes to avoid (6 patterns with BAD vs GOOD examples) - Testing your error handler (unit test examples) Operational impact: Orchestration code now has a canonical pattern. Claws can: - Copy-paste the run_claw_command() function (works for all commands) - Classify errors uniformly (no special cases per command) - Decide recovery deterministically (error.kind + retryable + cancel_observed) - Log/monitor/escalate with confidence Related cycles: - #178: Parse-error envelope (commands now emit structured JSON on invalid argv) - #179: Stderr hygiene + real message (JSON mode silences argparse, carries actual error) - #164 Stage B: cancel_observed field (callers know if session is safe for reuse) Updated CLAUDE.md: - Added ERROR_HANDLING.md to 'Related docs' section - Now documents the one-handler pattern as a guideline No code changes. No test changes. Pure documentation. This completes the documentation trail from protocol (SCHEMAS.md) → governance (OPT_OUT_AUDIT.md, OPT_OUT_DEMAND_LOG.md) → practice (ERROR_HANDLING.md). |
||
|
YeonGyu-Kim
|
3262cb3a87 |
docs: OPT_OUT_DEMAND_LOG.md — evidentiary base for governance decisions
Cycle #21 ships governance infrastructure, not implementation. Maintainership mode means sometimes the right deliverable is a decision framework, not code. Problem context: OPT_OUT_AUDIT.md (cycle #18 bonus) established 'demand-backed audit' as the next step. But without a structured way to record demand signals, 'demand-backed' was just a slogan — the next audit cycle would have no evidence to work from. This commit creates the evidentiary base: New file: OPT_OUT_DEMAND_LOG.md - Per-surface entries for all 12 OPT_OUT commands (Groups A/B/C) - Current state: 0 signals across all surfaces (consistent with audit prediction) - Signal entry template with required fields: - Source (who/what) - Use case (concrete orchestration problem) - Markdown-alternative-checked (why existing output insufficient) - Date - Promotion thresholds: - 2+ independent signals for same surface → file promotion pinpoint - 1 signal + existing stable schema → file pinpoint for discussion - 0 signals → stays OPT_OUT (rationale preserved) Decision framework for cycle #22 (audit close): - If 0 signals total: move to PERMANENTLY_OPT_OUT, close audit - If 1-2 signals: file individual promotion pinpoints with evidence - If 3+ signals: reopen audit, question classification itself Updated files: - OPT_OUT_AUDIT.md: Added demand log reference in Related section - CLAUDE.md: Added prerequisites for promotions (must have logged signals), added 'File a demand signal' workflow section Philosophy: 'Prevent speculative expansion' — schema bloat protection discipline. Every new CLAWABLE surface is a maintenance tax. Evidence requirement keeps the protocol lean. OPT_OUT surfaces are intentionally not-clawable until proven otherwise by external demand. Operational impact: Next cycles can now: 1. Watch for real claws hitting OPT_OUT surface limits 2. Log signals in structured format (no ad-hoc filing) 3. Run audit at cycle #22 with actual data, not speculation No code changes. No test changes. Pure governance infrastructure. Related: #18 cycle (OPT_OUT_AUDIT.md), maintainership phase transition. |
||
|
YeonGyu-Kim
|
8247d7d2eb |
fix: #179 — JSON mode now fully suppresses argparse stderr + preserves real error message
Dogfood discovered #178 had two residual gaps: 1. Stderr pollution: argparse usage + error text still leaked to stderr even in JSON mode (envelope was correct on stdout, but stderr noise broke the 'machine-first protocol' contract — claws capturing both streams got dual output) 2. Generic error message: envelope carried 'invalid command or argument (argparse rejection)' instead of argparse's actual text like 'the following arguments are required: session_id' or 'invalid choice: typo (choose from ...)' Before #179: $ claw load-session --output-format json [stdout] {"error": {"message": "invalid command or argument (argparse rejection)"}} [stderr] usage: main.py load-session [-h] ... main.py load-session: error: the following arguments are required: session_id [exit 1] After #179: $ claw load-session --output-format json [stdout] {"error": {"message": "the following arguments are required: session_id"}} [stderr] (empty) [exit 1] Implementation: - New _ArgparseError exception class captures argparse's real message - main() monkey-patches parser.error (+ all subparser.error) in JSON mode to raise _ArgparseError instead of print-to-stderr + sys.exit(2) - _emit_parse_error_envelope() now receives the real message verbatim - Text mode path unchanged: still uses original argparse print+exit behavior Contract: - JSON mode: stdout carries envelope with argparse's actual error; stderr silent - Text mode: unchanged — argparse usage to stderr, exit 2 - Parse errors still error.kind='parse', retryable=false Test additions (5 new, 14 total in test_parse_error_envelope.py): - TestParseErrorStderrHygiene (5): - test_json_mode_stderr_is_silent_on_unknown_command - test_json_mode_stderr_is_silent_on_missing_arg - test_json_mode_envelope_carries_real_argparse_message - test_json_mode_envelope_carries_invalid_choice_details (verifies valid-choices list) - test_text_mode_stderr_preserved_on_unknown_command (backward compat) Operational impact: Claws capturing both stdout and stderr no longer get garbled output. The envelope message now carries discoverability info (valid command list, missing-arg name) that claws can use for retry/recovery without probing the CLI a second time. Test results: 201 → 206 passing, 3 skipped unchanged, zero regression. Pinpoint discovered via dogfood at 2026-04-22 20:30 KST (cycle #20). |
||
|
YeonGyu-Kim
|
517d7e224e |
feat: #178 — argparse errors emit JSON envelope when --output-format json requested
Dogfood pinpoint: running 'claw nonexistent-command --output-format json' bypasses
the JSON envelope contract — argparse dumps human-readable usage to stderr with
exit 2, breaking the SCHEMAS.md guarantee that JSON mode returns structured output.
Problem:
$ claw nonexistent --output-format json
usage: main.py [-h] {summary,manifest,...} ...
main.py: error: argument command: invalid choice: 'nonexistent' (choose from ...)
[exit 2 — no envelope, claws must parse argparse usage messages]
Fix:
$ claw nonexistent --output-format json
{
"timestamp": "2026-04-22T11:00:29Z",
"command": "nonexistent-command",
"exit_code": 1,
"output_format": "json",
"schema_version": "1.0",
"error": {
"kind": "parse",
"operation": "argparse",
"target": "nonexistent-command",
"retryable": false,
"message": "invalid command or argument (argparse rejection)",
"hint": "run with no arguments to see available subcommands"
}
}
[exit 1, clean JSON envelope on stdout per SCHEMAS.md]
Changes:
- src/main.py:
- _wants_json_output(argv): pre-scan for --output-format json before parsing
- _emit_parse_error_envelope(argv, message): emit wrapped envelope on stdout
- main(): catch SystemExit from argparse; if JSON requested, emit envelope
instead of letting argparse's help dump go through
- tests/test_parse_error_envelope.py (new, 9 tests):
- TestParseErrorJsonEnvelope (7): unknown command, =syntax, text mode unchanged,
invalid flag, missing command, valid command unaffected, common fields
- TestParseErrorSchemaCompliance (2): error.kind='parse', retryable=false
Contract:
- text mode (default): unchanged — argparse dumps help to stderr, exits 2
- JSON mode: envelope per SCHEMAS.md, error.kind='parse', exit 1
- Parse errors always retryable=false (typo won't self-fix)
- error.kind='parse' already enumerated in SCHEMAS.md (no schema changes)
This closes a real gap: claws invoking unknown commands in JSON mode can now route
via exit code + envelope.kind='parse' instead of scraping argparse output.
Test results: 192 → 201 passing, 3 skipped unchanged, zero regression.
Pinpoint discovered via dogfood at 2026-04-22 19:59 KST (cycle #19).
|
||
|
YeonGyu-Kim
|
c73423871b |
docs: OPT_OUT_AUDIT.md — decision table for 12 exempt surfaces (#175–#177 prep)
Filed explicit decision criteria for the 12 OPT_OUT surfaces (commands that do not support --output-format json) documented in test_cli_parity_audit.py. Categorized by rationale: - Group A (4): Rich-Markdown reports (summary, manifest, parity-audit, setup-report) Markdown-as-output is intentional; JSON would be information loss. Unlikely promotions (remain OPT_OUT long-term). - Group B (3): List filters with --query/--limit (subsystems, commands, tools) Query layer already exists; users have escape hatch. Remain OPT_OUT (promotion effort >> value). - Group C (5): Simulation/debug surfaces (remote-mode, ssh-mode, teleport-mode, direct-connect-mode, deep-link-mode) Intentionally non-production; JSON output doesn't add value. Remain OPT_OUT (simulation tools, not orchestration endpoints). Audit workflow documented: 1. Survey: Check if external claws actually request JSON versions 2. Cost estimate: Schema + tests for each surface 3. Value estimate: Real demand vs hypothetical 4. Decision: CLAWABLE, remain OPT_OUT, or new pinpoint Promotion criteria locked (only if clear use case + schema simple + demand exists). Outcome prediction: All 12 likely remain OPT_OUT (documented rationale per group). Timeline: Survey period (cycles #19–#21), final decision (cycle #22). Related pinpoints: #175 (summary/manifest JSON parallel?), #176 (--query-json?), #177 (mode simulators ever CLAWABLE?). This closes the documentation loop from cycles #173–#174 (protocol closure → field evolution → reframe). Now governance rules are explicit for future work. |
||
|
YeonGyu-Kim
|
373dd9b848 |
docs: CLAUDE.md reframe — market Python harness as machine-first protocol validation layer
Rewrote CLAUDE.md to accurately describe the Python reference implementation: - Shifted framing from outdated Rust-focused guidance to protocol-validation focus - Clarified that src/tests/ is a dogfood surface proving SCHEMAS.md contract - Added machine-first marketing: deterministic, self-describing, clawable - Documented all 14 clawable commands (post-#164 Stage B promotion) - Added OPT_OUT surfaces audit queue (12 commands, future work) - Included protocol layers: Coverage → Enforcement → Documentation → Alignment - Added quick-start workflow for Python harness - Documented common workflows (add command, modify fields, promote OPT_OUT→CLAWABLE) - Emphasized protocol governance: SCHEMAS.md as source of truth - Exit codes documented as signals (0=success, 1=error, 2=timeout) Result: Developers can now understand the Python harness purpose without reading ROADMAP.md or inferring from test names. Protocol-first mental model is explicit. Related: #173 (protocol closure), #164 Stage B (field evolution), #174 (this cycle). |
||
|
YeonGyu-Kim
|
11f9e8a5a2 |
feat: #164 Stage B CLOSURE — turn-loop JSON + cancel_observed coverage + CLAWABLE promotion
Closes all three gaebal-gajae-identified closure criteria for #164 Stage B: 1. turn-loop runtime surface exposes cancel_observed consistently 2. cancellation path tests validate safe-to-reuse semantics 3. turn-loop promoted from OPT_OUT to CLAWABLE surface Changes: src/main.py: - turn-loop accepts --output-format {text,json} - JSON envelope includes per-turn cancel_observed + final_cancel_observed - All turn fields exposed: prompt, output, stop_reason, cancel_observed, matched_commands, matched_tools - Exit code 2 on final timeout preserved tests/test_cli_parity_audit.py: - CLAWABLE_SURFACES now contains 14 commands (was 13) - Removed 'turn-loop' from OPT_OUT_SURFACES - Parametrized --output-format test auto-validates turn-loop JSON tests/test_cancel_observed_field.py (new, 9 tests): - TestCancelObservedField (5 tests): field contract - default False - explicit True preserved - normal completion → False - bootstrap JSON exposes field - turn-loop JSON exposes per-turn field - TestCancelObservedSafeReuseSemantics (2 tests): reuse contract - timeout result has cancel_observed=True when signaled - engine.mutable_messages not corrupted after cancelled turn - engine accepts fresh message after cancellation - TestCancelObservedSchemaCompliance (2 tests): SCHEMAS.md contract - cancel_observed is always bool - final_cancel_observed convenience field present Closure criteria validated: - ✅ Field exposed in bootstrap JSON - ✅ Field exposed per-turn in turn-loop JSON - ✅ Field is always bool, never null - ✅ Safe-to-reuse: engine can accept fresh messages after cancellation - ✅ mutable_messages not corrupted by cancelled turn - ✅ turn-loop promoted from OPT_OUT (14 clawable commands now) Protocol now distinguishes at runtime: timeout + cancel_observed=false → infra/wedge (escalate) timeout + cancel_observed=true → cooperative cancellation (safe to retry) Test results: 182 → 192 passing, +10 tests, zero regression, 3 skipped unchanged. Closes #164 Stage B. Stage C (async-native preemption) remains future work. |
||
|
YeonGyu-Kim
|
97c4b130dc |
feat: #164 Stage B prep — add cancel_observed field to TurnResult
#164 Stage B requires exposing whether cancellation was observed at the turn-result level. This commit adds the infrastructure field: Changes: - TurnResult.cancel_observed: bool = False (query_engine.py) - _build_timeout_result() accepts cancel_observed parameter (runtime.py) - Two timeout paths now pass cancel_event.is_set() to signal observation (runtime.py) - bootstrap command includes cancel_observed in turn JSON (main.py) - SCHEMAS.md documents Turn Result Fields with cancel_observed contract Usage: When a turn timeout occurs, cancel_observed=true indicates that the engine observed the cancellation event being set. This allows callers to distinguish: - timeout with no cancel → infrastructure/network stall - timeout with cancel observed → cooperative cancellation was triggered Backward compat: - Existing TurnResult construction without cancel_observed defaults to False - bootstrap JSON output still validates per SCHEMAS.md (new field is always present) Test results: 182 passing, 3 skipped, zero regression. Related: #161 (wall-clock timeout), #164 (cancellation observability protocol) ROADMAP continues #164 with Stage C (test coverage for cancellation + turn envelope). |
||
|
YeonGyu-Kim
|
290ab7e41f |
feat: #173 — wrap_json_envelope() applied to all 13 clawable commands (LOOP CLOSED)
Completes the coverage → enforcement → documentation → alignment cycle.
Every clawable command now emits the canonical JSON envelope per SCHEMAS.md:
Common fields (now real in output):
- timestamp (ISO 8601 UTC)
- command (argv[1])
- exit_code (0/1/2)
- output_format ('json')
- schema_version ('1.0')
13 commands wrapped:
- list-sessions, delete-session, load-session, flush-transcript
- show-command, show-tool
- exec-command, exec-tool, route, bootstrap
- command-graph, tool-pool, bootstrap-graph
Implementation:
- Added wrap_json_envelope() helper in src/main.py
- Wrapped all 18 JSON output paths (13 success + 5 error paths)
- Applied exit_code=1 to error/not-found envelopes
- Kept text mode byte-identical (backward compat preserved)
Test updates:
- 3 skipped common-field tests now pass automatically
- 3 existing tests updated to verify common envelope fields while preserving command-specific field checks
- test_list_sessions_cli_runs, test_delete_session_cli_idempotent,
test_load_session_cli::test_json_mode_on_success
Full suite: 179 → 182 passing (+3 activated from skipped), zero regression.
Loop completion:
Coverage (#167-#170) ✅ All 13 commands accept --output-format
Enforcement (#171) ✅ CI blocks new commands without --output-format
Documentation (#172) ✅ SCHEMAS.md defines envelope contract
Alignment (#173 this) ✅ Actual output matches SCHEMAS.md contract
Example output now:
$ claw list-sessions --output-format json
{
"timestamp": "2026-04-22T10:34:12Z",
"command": "list-sessions",
"exit_code": 0,
"output_format": "json",
"schema_version": "1.0",
"sessions": ["alpha", "bravo"],
"count": 2
}
Closes ROADMAP #173. Protocol is now documented AND real.
Claws can build ONE error handler, ONE timestamp parser, ONE version check
instead of 13 special cases.
|
||
|
YeonGyu-Kim
|
ded0c5bbc1 |
test: #173 prep — JSON envelope field consistency validation
Adds parametrised test suite validating that clawable-surface commands'
JSON output matches their declared envelope contracts per SCHEMAS.md.
Two phases:
Phase 1 (this commit): Consistency baseline.
- Collect ENVELOPE_CONTRACTS registry mapping each command to its
required and optional fields
- TestJsonEnvelopeConsistency: parametrised test iterates over 13
commands, invokes with --output-format json, validates that
actual JSON envelope contains all required fields
- test_envelope_field_value_types: spot-check types (int, str, list)
for consistency
Phase 2 (future #173): Common field wrapping.
- Once wrap_json_envelope() is applied, all commands will emit
timestamp, command, exit_code, output_format, schema_version
- Currently skipped via @pytest.mark.skip, these tests will activate
automatically when wrapping is implemented:
TestJsonEnvelopeCommonFieldPrep::test_all_envelopes_include_timestamp
TestJsonEnvelopeCommonFieldPrep::test_all_envelopes_include_command
TestJsonEnvelopeCommonFieldPrep::test_all_envelopes_include_exit_code_and_schema_version
Why this matters:
- #172 documented the JSON contract; this test validates it
- Currently detects when actual output diverges from SCHEMAS.md
(e.g. list-sessions emits 'count', not 'sessions_count')
- As #173 wraps commands, test suite auto-validates new common fields
- Prevents regression: accidental field removal breaks the test suite
Current status: 11 passed (consistency), 6 skipped (awaiting #173)
Full suite: 168 → 179 passing, zero regression.
Closes ROADMAP #173 prep (framework for common field validation).
Actual field wrapping remains for next cycle.
|
||
|
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 |
||
|
YeonGyu-Kim
|
b048de8899 |
fix: #171 — automate cross-surface CLI parity audit via argparse introspection
Stops manual parity inspection from being a human-noticed concern. When
a developer adds a new subcommand to the claw-code CLI, this test suite
enforces explicit classification:
- CLAWABLE_SURFACES: MUST accept --output-format {text,json}
- OPT_OUT_SURFACES: explicitly exempt with documented rationale
A new command that forgets to opt into one of these two sets FAILS
loudly with TestCommandClassificationCoverage::test_every_registered_
command_is_classified. No silent drift possible.
Technique: argparse introspection at test time walks the _actions tree,
discovers every registered subcommand, and compares against the declared
classification sets. Contract is enforced machine-first instead of
depending on human review.
Three test classes covering three invariants:
TestClawableSurfaceParity (14 tests):
- test_all_clawable_surfaces_accept_output_format: every member of
CLAWABLE_SURFACES has --output-format flag registered
- test_clawable_surface_output_format_choices (parametrised over 13
commands): each must accept exactly {text, json} and default to 'text'
for backward compat
TestCommandClassificationCoverage (3 tests):
- test_every_registered_command_is_classified: any new subcommand
must be explicitly added to CLAWABLE_SURFACES or OPT_OUT_SURFACES
- test_no_command_in_both_sets: sanity check for classification conflicts
- test_all_classified_commands_actually_exist: no phantom commands
(catches stale entries after a command is removed)
TestJsonOutputContractEndToEnd (10 tests):
- test_command_emits_parseable_json (parametrised over 10 clawable
commands): actual subprocess invocation with --output-format json
produces valid parseable JSON on stdout
Classification:
CLAWABLE_SURFACES (13):
Session lifecycle: list-sessions, delete-session, load-session,
flush-transcript
Inspect: show-command, show-tool
Execution: exec-command, exec-tool, route, bootstrap
Diagnostic inventory: command-graph, tool-pool, bootstrap-graph
OPT_OUT_SURFACES (12):
Rich-Markdown reports (future JSON schema): summary, manifest,
parity-audit, setup-report
List filter commands: subsystems, commands, tools
Turn-loop: structured_output is future work
Simulation/debug: remote-mode, ssh-mode, teleport-mode,
direct-connect-mode, deep-link-mode
Full suite: 141 → 168 passing (+27), zero regression.
Closes ROADMAP #171.
Why this matters:
Before: parity was human-monitored; every new command was a drift
risk. The CLUSTER 3 sweep required manually auditing every
subcommand and landing fixes as separate pinpoints.
After: parity is machine-enforced. If a future developer adds a new
command without --output-format, the test suite blocks it
immediately with a concrete error message pointing at the
missing flag.
This is the first step in Gaebal-gajae's identified upper-level work:
operationalised parity instead of aspirational parity.
Related clusters:
- Clawability principle: machine-first protocol enforcement
- Test-first regression guard: extends TestTripletParityConsistency
(#160/#165) and TestFullFamilyParity (#166) from per-cluster
parity to cross-surface parity
|