symphony/
├── SPEC.md                          # Language-agnostic service specification (the contract)
├── README.md
├── LICENSE                          # Apache 2.0
├── NOTICE
│
├── .github/
│   ├── workflows/
│   │   ├── make-all.yml             # CI: format + lint + test + dialyzer
│   │   └── pr-description-lint.yml  # Enforces PR body format
│   ├── pull_request_template.md
│   └── media/                       # Demo video + screenshots
│
├── .codex/
│   ├── worktree_init.sh             # Git worktree bootstrap for Codex
│   └── skills/                      # Agent skills (invoked by Codex during execution)
│       ├── commit/SKILL.md          # Create logical commits
│       ├── push/SKILL.md            # Push branch to remote
│       ├── pull/SKILL.md            # Sync with origin/main
│       ├── land/SKILL.md            # Merge PR (retry loop until landed)
│       ├── linear/SKILL.md          # Raw Linear GraphQL operations
│       └── debug/SKILL.md           # Troubleshooting utilities
│
└── elixir/                          # Reference implementation (Elixir/OTP)
    ├── mix.exs                      # Project definition + deps
    ├── mix.lock
    ├── Makefile                     # `make all` = format + lint + coverage + dialyzer
    ├── WORKFLOW.md                  # Default workflow: YAML config + Jinja2 prompt template
    ├── AGENTS.md                    # Codex agent instructions for contributing
    ├── mise.toml                    # Elixir/Erlang version pinning
    │
    ├── config/
    │   └── config.exs               # Phoenix + app config (Logger, JSON, endpoint)
    │
    ├── docs/
    │   ├── token_accounting.md      # How token totals are tracked (critical: use absolute, not deltas)
    │   └── logging.md               # Structured log format and conventions
    │
    ├── lib/
    │   ├── symphony_elixir.ex       # Application entry point — starts Orchestrator, WorkflowStore, Supervisor
    │   │
    │   ├── symphony_elixir/
    │   │   ├── orchestrator.ex      # Core brain: poll loop, dispatch, retry queue, reconciliation, state
    │   │   ├── agent_runner.ex      # Per-issue task: workspace setup → Codex turns → cleanup
    │   │   ├── workflow.ex          # Parses WORKFLOW.md (YAML front matter + Jinja2 prompt body)
    │   │   ├── workflow_store.ex    # GenServer: caches + hot-reloads WORKFLOW.md on file change
    │   │   ├── config.ex            # Typed config getters with NimbleOptions validation
    │   │   ├── workspace.ex         # Filesystem workspace lifecycle (create, hooks, remove, cleanup)
    │   │   ├── prompt_builder.ex    # Renders Jinja2 template with issue context variables
    │   │   ├── cli.ex               # CLI entry point (escript) — parses args, starts app
    │   │   ├── tracker.ex           # Behaviour definition for issue tracker adapters
    │   │   ├── log_file.ex          # Per-issue log file writer
    │   │   ├── status_dashboard.ex  # Terminal ANSI dashboard: sparklines, tables, token graphs
    │   │   ├── http_server.ex       # Starts Phoenix endpoint (optional, via config)
    │   │   ├── specs_check.ex       # Validates implementation against SPEC.md requirements
    │   │   │
    │   │   ├── tracker/
    │   │   │   └── memory.ex        # In-memory tracker for testing (no Linear dependency)
    │   │   │
    │   │   ├── linear/              # Linear issue tracker integration
    │   │   │   ├── adapter.ex       # Implements Tracker behaviour — fetch, comment, update state
    │   │   │   ├── client.ex        # GraphQL HTTP client with pagination (batch size 50)
    │   │   │   └── issue.ex         # Issue struct: normalize Linear API → internal model
    │   │   │
    │   │   └── codex/               # Codex app-server integration
    │   │       ├── app_server.ex    # JSON-RPC 2.0 over stdio: init → thread → turns → stop
    │   │       └── dynamic_tool.ex  # Runtime-injected tools (linear_graphql)
    │   │
    │   └── symphony_elixir_web/     # Phoenix web layer (observability dashboard)
    │       ├── endpoint.ex          # Cowboy/Bandit HTTP endpoint
    │       ├── router.ex            # Routes: / (LiveView), /api/v1/* (JSON API)
    │       ├── presenter.ex         # Converts orchestrator state → JSON/template data
    │       ├── observability_pubsub.ex  # PubSub for real-time dashboard updates
    │       ├── static_assets.ex     # Serves dashboard CSS
    │       ├── error_json.ex
    │       ├── error_html.ex
    │       ├── components/
    │       │   └── layouts.ex       # HTML layout for LiveView
    │       ├── live/
    │       │   └── dashboard_live.ex  # Real-time Phoenix LiveView dashboard
    │       └── controllers/
    │           ├── observability_api_controller.ex  # JSON API: GET /state, POST /refresh, GET /:id
    │           └── static_asset_controller.ex
    │
    ├── priv/
    │   └── static/
    │       └── dashboard.css        # Dashboard styles
    │
    └── test/                        # Comprehensive test suite
        ├── test_helper.exs
        ├── support/
        │   ├── test_support.exs     # Shared test helpers
        │   └── snapshot_support.exs # Snapshot testing for dashboard output
        ├── fixtures/                # Golden-file snapshots for status dashboard
        └── symphony_elixir/         # Unit + integration tests per module

%Issue{
  id:             string        # Linear internal UUID
  identifier:     string        # Human-readable key, e.g. "PROJ-123"
  title:          string
  description:    string | nil
  priority:       1..4 | nil    # Lower = higher priority in dispatch sorting
  state:          string        # "Todo", "In Progress", "Done", etc.
  branch_name:    string | nil  # Git branch from Linear
  url:            string | nil  # Linear issue URL
  assignee_id:    string | nil
  labels:         [string]      # Normalized to lowercase
  blocked_by:     [%{type, issue: %{id, identifier, state}}]
  created_at:     DateTime | nil
  updated_at:     DateTime | nil
}

%State{
  poll_interval_ms:          integer         # Polling cadence (default 5000)
  max_concurrent_agents:     integer         # Global concurrency cap (default 10)
  running:                   %{issue_id => RunningEntry}
  completed:                 MapSet<issue_id>
  claimed:                   MapSet<issue_id>
  retry_attempts:            %{issue_id => RetryEntry}
  codex_totals:              %{input_tokens, output_tokens, total_tokens, seconds_running}
  codex_rate_limits:         %{...}         # Extracted from Codex token usage events
}

%RunningEntry{
  pid:                  pid             # Task process
  ref:                  reference       # Monitor ref
  identifier:          string          # "PROJ-123"
  issue:               %Issue{}
  session_id:          string | nil    # "thread-{id}-turn-{n}"
  turn_count:          integer
  retry_attempt:       integer | nil
  started_at:          DateTime
  codex_input_tokens:  integer
  codex_output_tokens: integer
  codex_total_tokens:  integer
  last_codex_event:    atom | nil
  last_codex_message:  string | nil
  last_codex_timestamp: DateTime | nil
}

%RetryEntry{
  attempt:     integer
  timer_ref:   reference
  due_at_ms:   integer
  identifier:  string
  error:       string | nil
}

SESSION LIFECYCLE:
  → initialize             (capabilities exchange)
  ← initialized
  → thread/start           (sandbox policy, cwd, dynamic tools)
  ← thread_id

PER-TURN:
  → turn/start             (prompt, issue metadata, workspace path)
  ← notifications...       (progress, tool calls, token usage)
  ← turn/completed

  Tool call flow:
    ← request: {method: "tool/call", params: {name: "linear_graphql", arguments: {...}}}
    → response: {result: {success: true, contentItems: [...]}}

TOKEN REPORTING:
  ← thread/tokenUsage/updated   (absolute totals per thread — NOT deltas)

SESSION END:
  → close port