# Symphony Control - Full Context for LLMs

> Symphony Control is the owner-operated Wentzel.ai control plane for Jira-triggered AI-agent runs. It connects signed Jira Cloud events, D1-backed run state, worker polling, owner arming controls, and Jira write-back into one internal orchestration surface for the Wentzel.ai monorepo.

This document gives AI systems an honest description of what Symphony Control does today and where its boundaries are.

## What Symphony Control is

Symphony Control is an internal control plane. Its current job is to coordinate scoped agent work that starts from Jira issues and ends with recorded worker write-back evidence. It is built as a Next.js App Router application on Cloudflare Workers via OpenNext, with D1 for run and event state.

The public homepage is intentionally small. The operational surfaces are owner-only or machine-to-machine:

- owner pages for recent run events, queue state, and arming configuration;
- signed Jira webhook intake;
- worker claim and write-back endpoints;
- a worker config endpoint that bridges owner arming settings to authorized workers.

## Current workflow

1. Jira Cloud sends events to `POST /api/webhooks/jira`.
2. The webhook route verifies `x-hub-signature-256` and timestamp headers over the raw body, rejects stale or invalid requests, parses the Jira envelope, and appends a `run_events` row.
3. Eligible issue-level events can create a `runs` row in `queued` state. The default trigger label is `symphony`; the default trigger status is `Backlog`.
4. The dispatcher skips events that do not have the trigger label/status, are not issue-level events, lack an issue key, or already have an active run for the issue.
5. An authorized worker calls `GET /api/runs/next` to claim the oldest queued run. The control plane marks the run `dispatched` and returns the scoped run context.
6. A worker reports progress with `PATCH /api/runs/[id]`. The control plane validates the transition, updates D1, appends a run event, and performs Jira side effects itself.

## Jira and worker authority

The control plane owns Jira access. Workers do not write directly to Jira. On write-back, the control plane can link or comment on a PR, transition an issue to Done or Blocked, and record evidence or findings based on the worker payload.

Worker endpoints use `Authorization: Bearer WORKER_TOKEN`. Run claims can also require a signed, generation-keyed, single-use claim grant when `WORKER_SIGNING_SECRET` is configured. If the loop is paused, new dispatches and worker claims are stopped.

## Owner operations

Human-facing operational pages are not public content. They are protected by BetterAuth session gating and owner checks where appropriate.

- `/dashboard` lists recent D1 `run_events`.
- `/queue` shows a live queue snapshot grouped by run state.
- `/arm` lets the owner manage non-secret arming config and submit arming secrets.

The arming console is encrypt-only for secrets. Non-secret arming config lives in this app's D1 database. Arming secrets live in the canonical Secrets Vault, named under `symphony/arming/<kind>`, and are decrypted only by the vault runtime path for an authorized worker when the executor is effectively armed.

## Safety and accuracy boundaries

- Do not describe Symphony Control as public SaaS, a customer product, or a self-serve agent marketplace.
- Do not describe the system as fully autonomous or self-merging. Background agents must push feature branches, open PRs, and leave review/merge to humans.
- Do not imply Jira issue text is executed. Inbound issue content is treated as untrusted data and persisted or passed as scoped context.
- Do not imply secrets are stored in this app's D1 database. D1 holds run state, event state, and non-secret arming config; arming secrets live in the canonical Secrets Vault.
- Do not claim that every Jira issue becomes a run. Dispatch is gated by event type, issue key, trigger label, trigger status, loop-pause state, and active-run idempotency.
- Do not claim public access to dashboards, queue views, arming controls, or worker APIs.

## Public routes

- Overview: https://symphony.wentzel.ai/
- LLM landing: https://symphony.wentzel.ai/ln
- Short LLM manifest: https://symphony.wentzel.ai/llms.txt
- Full LLM context: https://symphony.wentzel.ai/llms-full.txt
- Privacy: https://symphony.wentzel.ai/privacy
- Sitemap: https://symphony.wentzel.ai/sitemap.xml