Epic: First-class derivatives discovery, spread analysis, and safe execution

[felipecsl]

Summary

Expand huskly-cli into a first-class derivatives workflow so contract research, spread analysis, broker validation, execution, and lifecycle monitoring no longer require custom IBKR scripts.

The motivating workflow was an Aug 21 2026 NDXP/NQ put-credit-spread exploration. It exposed gaps in:

• exact FOP/index-option contract discovery
• NDX versus NDXP and NQ trading-class identity
• liquidity and market-data inspection
• multiplier-aware spread R/R calculations
• IBKR What-If and permission diagnostics
• atomic combo construction and signed credit encoding
• explicit broker warning replies
• status monitoring, verification, and cancellation
• CLI/MCP parity

Desired workflow

resolve exact contracts
        ↓
inspect chain and liquidity
        ↓
quote and analyze vertical
        ↓
explicit broker What-If preview
        ↓
review short-lived preview identity
        ↓
confirmed atomic submission
        ↓
warning acknowledgement, status, fills, cancellation

Tracking issues

Implementation order:

• Add broker-neutral derivative identity and IBKR OPT/FOP discovery capabilities #46 — Broker-neutral derivative identity and IBKR OPT/FOP discovery capabilities
• Add broker-neutral option discovery and vertical-spread analytics #47 — Broker-neutral option discovery and vertical-spread analytics
• Add IBKR spread What-If previews and trading diagnostics #48 — IBKR spread What-If previews and trading diagnostics
• Add confirmed atomic vertical execution, warnings, and order lifecycle #49 — Confirmed atomic vertical execution, warning handshake, lifecycle, and MCP parity

The first two stages are read-only. #48 may call the explicitly selected IBKR What-If endpoint but must never place an order. #49 is the only stage authorized to add live-write behavior.

Product direction

Add cohesive namespaces rather than more unrelated top-level commands:

huskly-cli option resolve ...
huskly-cli option chain ...
huskly-cli spread quote put-credit ...
huskly-cli spread preview put-credit ...
huskly-cli spread submit <preview-id> --confirm
huskly-cli order show|watch|cancel ...

Retain existing top-level commands as compatibility aliases where practical.

Start with vertical call/put credit and debit spreads. Do not begin with an arbitrary N-leg builder.

Architecture direction

• Use capability-specific derivative and multi-leg order interfaces instead of turning the existing shared BrokerClient into a monolith.
• Put normalized contract identity, spread construction, payoff math, and preview lifecycle in reusable application/domain services.
• Make CLI and MCP thin interfaces over those same services.
• Keep IBKR security-definition state, conids, combo encoding, manual/operator metadata, What-If, warning replies, and lifecycle normalization inside @huskly/ibkr-client.
• Keep semantic durable identity separate from broker-local conids and OCC encodings.
• Support stable JSON output for every exploratory operation.
• Treat combo market prices derived from leg quotes as synthetic, not as a combo NBBO.

Cross-cutting safety contract

• Exact account selection; never silently select the first account.
• Mask account identifiers in normal output.
• Show live versus paper environment before preview and submission.
• What-If is the authoritative permission/economic gate; metadata remains advisory.
• Positive user-facing credit/debit values; broker-specific signed encoding stays internal.
• Multi-leg orders default to limit-only.
• Short-lived preview identity covers all material order terms.
• Submission rejects expiry, account mismatch, environment mismatch, and economic drift.
• Each broker warning requires explicit acknowledgement; unknown warnings fail closed.
• Never globally suppress warning categories.
• Bypass stale caches for preview, placement, status verification, and cancellation.
• Verify exact legs and terms after submission.
• Cancellation succeeds only after terminal state is observed.
• Live acceptance tests are opt-in and require an exact account allowlist.
• No generic raw broker endpoint command as the primary escape hatch.

Program-level acceptance criteria

• NQ FOP and NDXP option chains can be explored without custom scripts.
• The Aug 21 2026 26600/26400 put vertical can be analyzed with correct multiplier-aware R/R.
• Quote freshness, market-data availability, volume, OI, IV, and Greeks are represented honestly.
• An IBKR What-If preview reports margin, commissions/fees, and warnings without submission.
• A reviewed preview can be submitted as one atomic combo with explicit confirmation.
• Warning, fill, partial-fill, rejection, cancel, and terminal status are normalized and observable.
• CLI and MCP behavior share application services and safety invariants.
• Existing Schwab commands remain compatible.
• Documentation includes NQ FOP and NDXP examples plus a live-trading safety section.

Non-goals

• Autonomous or scheduled strategy execution.
• Arbitrary N-leg strategies in the first release.
• Automatic broker-warning suppression.
• Default market orders for option spreads.
• Persisting broker conids as durable strategy identity.

[felipecsl]

Epic completion audit passed.

Delivered and merged individually:

• Add broker-neutral derivative identity and IBKR OPT/FOP discovery capabilities #46: upstream huskly/ibkr-client#18, CLI feat: add broker-neutral derivative discovery #51, npm @huskly/ibkr-client@0.8.0
• Add broker-neutral option discovery and vertical-spread analytics #47: upstream huskly/ibkr-client#19, CLI feat: add derivative spread research #52, npm @huskly/ibkr-client@0.9.0
• Add IBKR spread What-If previews and trading diagnostics #48: upstream huskly/ibkr-client#20, CLI feat: add derivative what-if previews #53, npm @huskly/ibkr-client@0.10.0
• Add confirmed atomic vertical execution, warnings, and order lifecycle #49: upstream huskly/ibkr-client#21, CLI feat: execute reviewed derivative spreads #54, npm @huskly/ibkr-client@0.11.0

Every PR passed its repository CI before merge. Final merged huskly/cli main was reinstalled with yarn install --frozen-lockfile; lint, formatting, strict typechecking, all 56 tests, and build passed. Registry verification confirms versions 0.8.0–0.11.0 exist and latest is 0.11.0.

The implementation remains grounded in captured NQ QN3 and NDX/NDXP broker response shapes; ordinary CI performs no live brokerage writes.