Imports:
  - Types:
      - SwaxContext
    Usages:
      - cli-facade
    From: swax/cli
  - Types:
      - run_plan
    Usages:
      - plan AS plan-usage
    From: swax/applications
  - Types:
      - MissingEnvironmentVariablesError
    Usages:
      - environment
    From: swax/config
  - Types:
      - SpecParseError
    Usages:
      - parsing
    From: swax/openapi
  - Types:
      - RepositoryCloneError
      - SpecsNotFoundError
    Usages:
      - specs-repository
    From: swax/git
  - Types:
      - TraceabilityGraphMissingError
    Usages:
      - affected-endpoints
    From: swax/traceability
  - Types:
      - LLMCallError
      - LLMRateLimitedError
      - LLMResponseParseError
      - UnsupportedLLMProtocolError
    Usages:
      - llm-transport
    From: swax/llm

Usages:
  conventions: .goga/usages/conventions.md
  click: .goga/usages/cooks/click.md

Annotations: |
  Thin CLI handler: exception mapping only. All orchestration lives in `run_plan`.
  Every domain exception is mapped to click.ClickException with a user-facing message.
  The returned Markdown is echoed to stdout.

  Use `conventions` for code writing rules and testing.
  Use `click` for the command decorator, echo, and error mapping.
  Use `plan-usage` for `run_plan` semantics.
  Use `environment` for `MissingEnvironmentVariablesError`.
  Use `parsing` for `SpecParseError`.
  Use `specs-repository` for `RepositoryCloneError` and `SpecsNotFoundError`.
  Use `affected-endpoints` for `TraceabilityGraphMissingError`.
  Use `llm-transport` for the LLM error types.
  Use `cli-facade` for the `SwaxContext` access pattern.

---

"plan(ctx: click.Context)":
  location: plan.py
  annotations: |
    Click handler for the plan command: delegates to `run_plan`, echoes the report, and maps domain exceptions to user-facing errors.

    `ctx`: Click context whose obj is a `SwaxContext`.

    Algorithm:
    1. Resolve ctx.obj as `SwaxContext` via @click.pass_obj.
    2. Resolve project_root from the current working directory.
    3. Delegate to `run_plan` inside a try.
    4. Echo the returned Markdown to stdout.
    5. Map every documented domain exception to click.ClickException: `MissingEnvironmentVariablesError`,
       `SpecParseError`, `RepositoryCloneError`, `SpecsNotFoundError`, `TraceabilityGraphMissingError`,
       `LLMRateLimitedError`, `LLMCallError`, `UnsupportedLLMProtocolError`, `LLMResponseParseError`.

    Requirements:
    - No interactive prompts — plan reads everything from .swax/config.yml and the environment.
    - Exit code 0 on success, 1 on any ClickException.

    Constraints:
    - Do not catch generic Exception — only the documented domain exceptions.
    - Do not retry rate-limited calls.
    - SWAX_LLM_TOKEN never appears in any error message or echoed output.

---

Author: Goga
CreatedAt: 30/07/26
Description: |
  Click handler for the plan command — delegates to run_plan, echoes the report, and maps
  domain errors to ClickException.
