feat: add allium behavioral specs

[exilis]

Behavioral Specifications

Machine-distilled from source code using allium-spec-distillation.

credential-resolution

External Entities

Review notes:

• [minor] CredentialsRequested event used in SelectProfileName's when: clause but never explicitly declared as a trigger or surface; its shape (requested_profile?) is only implied by usage

oauth-flow

Authorization-code OAuth2 flow for CLI user authentication.
Currently restricted to paper trading; live trading requires API keys until PKCE is added.

Review notes:

• [minor] config.token_exchange_timeout is declared but never referenced in any rule; either wire it to a rule or remove it

http-client

Value Types

Review notes:

• [minor] RequestError value type is declared but never referenced in any rule ensures or requires clause — appears orphaned
• [minor] HttpClient.timeout field is declared but no rule models timeout behaviour (e.g. request failing or retrying on timeout)
• [minor] No rule covers non-rate-limit client error responses (4xx other than 429) — silent gap in the response-handling lifecycle

output-contract

Two-tier output model: API commands emit structured data (JSON or CSV)
to stdout with JSON errors on stderr; operational commands emit plain
text. Covers jq-filter transformation and CSV formatting support.

hand-authored-commands

Scope: Hand-authored CLI command logic for the Alpaca CLI
Includes: bracket-order leg construction with time-in-force defaulting,
watchlist by-name asset removal, self-update discovery and upgrade,
doctor diagnostics, credential profile management
Excludes: generated Cobra command tree (internal/cmd/commands.gen.go),
raw API passthrough (api.go), factory helpers (factory.go),
help-all rendering (help_all.go)

code-generator

Scope: OAS-driven code generation pipeline in cmd/generate/
Includes: command registry (CommandMapping), generation pipeline, coverage validation
Excludes:
- Output files: internal/api/*.gen.go, internal/cmd/commands.gen.go
- Hand-written extension points: bodyHook and configureFunc implementations
- OAS specification source files (api/specs/)

Review notes:

• [minor] output_path in RunGenerator rule uses literal string "internal/api/descriptions.gen.go" and "internal/cmd/commands.gen.go" — these are implementation-level paths rather than domain terms; consider replacing with symbolic path references or abstract output identifiers
• [minor] type_output_path() and client_output_path() helper functions are referenced in ensures: clauses but never declared in the spec; their signatures and semantics are implicit

---

🤖 Generated with allium-spec-distillation