# Advisory Supervisor Architecture

## Purpose

GH-333 defines an epic for extending Open Orchestra advisory mode into a
supervisor that finds improvement opportunities from local lessons and generated
prompt context. The supervisor remains offline-first, publishes findings only
through explicit user action, and uses guarded GitHub workers for evaluation.

## Existing Product Surface

Open Orchestra already has `advisory` mode:

- `orchestra init --advisory` creates `.agent-workflow/advisory/` without
  writing root instruction files.
- `orchestra advisory convert` promotes advisory artifacts into local workflow
  tasks.
- `orchestra memory query` retrieves bounded lessons and prompt registry
  entries.
- `orchestra doc-sync audit` already produces recommendations from local
  project state.

The supervisor should extend this namespace instead of introducing a parallel
`advisor` product concept.

## MVP Architecture

```mermaid
flowchart LR
  subgraph local["Local workspace"]
    lessons["agent lessons"]
    prompts["generated prompts"]
    scan["orchestra advisory scan"]
    findings[".agent-workflow/advisory/findings"]
    publish["orchestra advisory publish"]
  end

  subgraph github["GitHub"]
    issue["advisor:finding issue"]
    triage["triage worker<br/>no secrets"]
    eval["container evaluator<br/>least privilege"]
  end

  subgraph guardrails["Guardrails"]
    redact["secret redaction"]
    injection["prompt-injection scan"]
    policy["policy decision"]
  end

  lessons --> scan
  prompts --> scan
  scan --> redact
  redact --> injection
  injection --> findings
  findings --> publish
  publish --> issue
  issue --> triage
  triage --> policy
  policy -->|safe or approved| eval
  policy -->|blocked| issue
```

MVP commands:

- `orchestra advisory scan`
- `orchestra advisory suggest`
- `orchestra advisory publish`
- `orchestra advisory worker-policy`

MVP storage:

- `.agent-workflow/advisory/findings/*.json`
- `.agent-workflow/advisory/findings/*.md`
- `.agent-workflow/advisory/policy.json`

MVP finding fields:

- `id`
- `title`
- `summary`
- `sources`
- `sourceType`: `lesson | prompt | evidence | decision | mixed`
- `confidence`
- `riskLevel`
- `impactedPaths`
- `proposedAcceptanceCriteria`
- `labels`
- `policyStatus`: `draft | safe | needs_review | blocked | published`
- `guardrailFindings`

MVP GitHub labels:

- `advisor:finding`
- `advisor:needs-review`
- `advisor:approved`
- `advisor:blocked`
- `advisor:security`
- `advisor:prompt`
- `advisor:workflow`
- `advisor:docs`

The GitHub worker must trigger only on the specific advisor finding
classification. The first job runs without secrets and with minimal
permissions. Container evaluation is allowed only after the finding passes
guardrails or receives maintainer approval.

## To-Be Architecture

```mermaid
flowchart LR
  subgraph workspace["Workspace control plane"]
    supervisor["advisory supervisor"]
    memory["bounded memory packet"]
    findings["finding ledger"]
    githubPublisher["GitHub publisher"]
  end

  subgraph policy["Policy and guardrails"]
    promptSecurity["prompt-injection detector"]
    secrets["secret classifier"]
    evaluatorPolicy["execution policy"]
    audit["audit trail"]
  end

  subgraph external["Execution options"]
    githubWorker["GitHub worker"]
    localProvider["local provider<br/>Ollama / Queen / OpenCode"]
    saas["optional SaaS<br/>sanitized payloads"]
  end

  memory --> supervisor
  supervisor --> promptSecurity
  supervisor --> secrets
  promptSecurity --> evaluatorPolicy
  secrets --> evaluatorPolicy
  evaluatorPolicy --> findings
  findings --> githubPublisher
  githubPublisher --> githubWorker
  findings --> localProvider
  findings --> saas
  githubWorker --> audit
  localProvider --> audit
  saas --> audit
```

The SaaS option is not required for local operation. If introduced, it should
receive sanitized finding payloads and policy metadata, not raw prompt history,
raw lesson logs, repository secrets, or privileged tokens. Repository execution
remains in GitHub Actions or an equivalent isolated runner.

## Diagram Authoring Strategy

Mermaid remains useful for lightweight architecture docs, but it does not
provide enough control for high-fidelity recreation of Lucid or PDF diagrams.
Precise spacing, connector bends, line avoidance, container dimensions, border
styles, and exact colors require a layout-preserving format.

Use draw.io XML as the high-fidelity source format:

- version `.drawio` files as source artifacts.
- export deterministic `.svg` files for docs and the site.
- keep element geometry, connector waypoints, colors, borders, and typography
  in the XML.
- validate that generated SVG exists and is non-empty before release.

Proposed future commands:

- `orchestra diagrams convert --from <file.pdf|file.svg> --to <file.drawio>`
- `orchestra diagrams export --file <file.drawio> --format svg`
- `orchestra diagrams lint --file <file.drawio>`

For PDF recreation, the process should capture:

- container positions and dimensions.
- internal and external spacing.
- connector routing and bend points.
- line avoidance around elements.
- fill, stroke, border, and text hex colors.
- typography, wrapping, and relative sizing.
- final resizing after real text is placed.

Draw.io export should run offline where possible. If the diagrams.net desktop or
CLI exporter is unavailable, the command should report exact installation or
manual export guidance instead of silently generating an approximation.

## Security Boundaries

- Treat lessons, prompt registry entries, GitHub issues, comments, and PDFs as
  untrusted input.
- Never pass secrets or raw unbounded prompt history to a provider.
- Do not use shell interpolation. Execute provider and diagram tools with
  argument arrays.
- Validate all file paths against the workspace root.
- Block or require human approval when prompt content asks to ignore policies,
  reveal secrets, alter workflow permissions, or exfiltrate data.
- Keep worker permissions explicit and minimal.

## Child Stories

1. Advisory finding schema and local scan.
2. Provider adapter contract for local runtimes.
3. GitHub issue publication and label taxonomy.
4. GitHub worker MVP with no-secret triage.
5. Prompt-injection and secret guardrails.
6. Draw.io XML source and SVG export support.
7. Optional SaaS-ready sanitized finding event contract.