fix(cascade-tools): accept --boolFlag value + wrap oclif parse errors in envelope

[zbigniewsobiecki]

Summary

Closes the dominant cascade-tools failure mode from the 2026-05-09 prod log analysis: 9/14 codex runs that called pm read-work-item failed with --includeComments true, exit 2, and empty stdout (no diagnostic envelope), then looped on help-reads to recover.

Two coupled regressions against spec 014:

1. The prompt taught a syntax the CLI rejected. nativeToolPrompts.formatParam rendered # example: --includeComments 'true' for any boolean param whose examples array carried a literal true|false. Oclif's Flags.boolean({ allowNo: true }) rejects that form at parse time, contradicting the synopsis it had just rendered ([--no-includeComments]). Codex agents followed the example. This is the "no prompt lying" rule — fixed once for arrays in spec 014, never closed for booleans+examples.
2. Parse-time errors bypassed the structured envelope. FailedFlagValidationError, FlagInvalidOptionError, and UnexpectedArgsError escaped cliCommandFactory's existing unknown-flag catch and exited with code 2 + empty stdout — the agent had nothing to self-correct from. Spec 014 promised every flag-parse failure would emit { error: { type, flag, got, expected, hint } }; for the three classes oclif throws at parse time, that promise was silently broken.

Changes

src/backends/shared/nativeToolPrompts.ts — formatParam special-cases type === 'boolean' for the per-flag example line: emits the canonical toggle (# example: --key for true, # example: --no-key for false) instead of the rejected value form.

src/gadgets/shared/cliCommandFactory.ts —

• massageBooleanFlagValues argv preprocessor: accepts --key true|false|yes|no|1|0 (space- or equals-separated, case-insensitive), rewrites to oclif's canonical --key / --no-key before parsing. Malformed values surface inline through emitCliError as a flag-parse envelope with got, expected, and hint populated — agents get exactly what they need to retry. Pass-through for undefined argv keeps existing tests green.
• classifyParseError wraps the three oclif parse-time error classes:
  • FailedFlagValidationError → { type: 'missing-required', flag, hint }
  • FlagInvalidOptionError → { type: 'enum-mismatch', flag, got, expected }
  • UnexpectedArgsError → { type: 'flag-parse', got } (catches any boolean-value miss the preprocessor doesn't see)
• Generic CLIParseError fallback maps to flag-parse. Existing unknown-flag + Levenshtein "did you mean" path is preserved.

Static guard at tests/unit/gadgets/shared/promptExamplesGrammar.test.ts — iterates all 23 production gadget definitions (pm + github + sentry + session) and asserts the rendered prompt never contains --<bool-flag> 'true' / 'false' for any boolean param. Verified to fail loudly when the renderer fix is reverted.

End-to-end smoke (built CLI, no creds)

$ cascade-tools pm read-work-item --workItemId X --includeComments true
# → parses through to gadget body (real Trello call attempted) — no more silent exit 2

$ cascade-tools pm read-work-item --workItemId X --includeComments banana
{"success":false,"error":{"type":"flag-parse","flag":"includeComments","got":"banana",
 "expected":"true|false|yes|no|1|0",
 "hint":"Use --includeComments or --no-includeComments for the canonical toggle form."}}

$ cascade-tools pm read-work-item
{"success":false,"error":{"type":"missing-required","flag":"workItemId",
 "hint":"pass --workItemId <value> (see --help for the full signature)"}}

$ cascade-tools pm update-checklist-item --workItemId X --checkItemId Y --state banana
{"success":false,"error":{"type":"enum-mismatch","flag":"state","got":"banana",
 "expected":"complete, incomplete"}}

Test plan

• Unit suite — 9007 / 9007 passing
• tests/unit/backends/shared-nativeToolPrompts.test.ts — 38 / 38 (2 new boolean-example cases)
• tests/unit/cli/cli-command-factory.test.ts — 35 / 35 (14 new: 10 boolean-value-form parametrized + bare toggle + envelope on malformed + enum-not-affected guard + 3 parse-error wraps)
• tests/unit/gadgets/shared/promptExamplesGrammar.test.ts — 3 / 3 (new static guard; verified fails on revert)
• npm run lint clean (the 2 remaining noExcessiveCognitiveComplexity warnings are pre-existing in materialize.ts + sentry/webhook-handler.ts)
• npm run typecheck clean
• Pre-push hook — full unit suite (3154 tests) green
• End-to-end smoke against built CLI — see snippet above

Out of scope

The DEBUG/ANSI noise leaking into cascade-tools stdout (issue #2 in analyze-recent-25-runs-swirling-pearl.md — 75/120 calls polluted) and the misleading cascade-tools --help topic descriptions (issue #3) are independent fixes; will land in follow-up PRs.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 77.35849% with 36 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/gadgets/shared/cliCommandFactory.ts	77.63%	34 Missing ⚠️
src/backends/shared/nativeToolPrompts.ts	71.42%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[nhopeatall]

Summary

Requesting changes because boolean value-form parsing still rejects false for a shipped boolean flag that does not declare allowNo.

Code Issues

Should Fix

• src/gadgets/shared/cliCommandFactory.ts:396 — massageBooleanFlagValues rewrites every recognized false value to --no-${name}. That only parses for booleans declared with allowNo. scm create-pr has a real boolean flag, draft, without allowNo; --draft false and --draft=false are rewritten to --no-draft, which oclif rejects as an unknown flag. I verified this with a local factory smoke: --draft true reaches the core with { draft: true }, but both false forms emit an unknown-flag envelope for --no-draft. This leaves the PR's promised --boolFlag true|false support incomplete for one of the production commands.

🕵️ codex · gpt-5.5 · run details

[nhopeatall]

This rewrite is only valid for flags whose ParameterDefinition has allowNo. For non-negatable booleans like scm create-pr's draft, --draft false / --draft=false becomes --no-draft and fails as an unknown flag instead of accepting the explicit false value. The preprocessor needs to track whether each boolean supports negation, or otherwise consume false values without producing an unsupported --no-* flag.

[aaight]

Fixed. The root issue was that collectBooleanFlagNames returned a plain Set<string> with no information about whether each flag supports --no-<name> negation. The preprocessor then blindly emitted --no-draft for any boolean flag receiving a false value.

Change made: collectBooleanFlagNames now returns Map<string, boolean> where the value is the allowNo property from the flag's BooleanParameterDefinition. massageBooleanFlagValues reads that map and:

• normalized === false + allowNo === true → emit --no-${name} (existing behaviour for commit, push, includeComments)
• normalized === false + allowNo === false → consume the token and emit nothing (flag absence = false, which is the correct oclif result for non-negatable booleans like draft)

The error hint for malformed values is also narrowed — non-negatable flags no longer suggest --no-${name} as a valid alternative.

Three new tests cover the draft-style case: --draft false (space-separated), --draft=false (equals-separated), and --draft true (still works).

[nhopeatall]

LGTM - The boolean value preprocessor preserves existing toggle behavior, handles non-allowNo booleans like draft, and parse-time oclif errors now emit structured envelopes. Focused unit tests passed locally.

🕵️ codex · gpt-5.5 · run details