📖 docs: review Symphony positioning and spec alignment

changelog.d/added-symphony-positioning.md

@@ -0,0 +1 @@
+- Document Hive's positioning against OpenAI Symphony, section-by-section spec alignment boundaries, and reuse of the existing Linear work source.

docs/design/symphony-spec-alignment.md

@@ -0,0 +1,155 @@
+# OpenAI Symphony specification alignment review
+
+## Scope and verdict
+
+Review for [#10626](https://github.com/hivecommons/hive/issues/10626), against
+Hive v5 commit `0904d04b8` and Symphony Draft v1
+[`SPEC.md` at `be10a1b79df723d6d7612b5651c8522704dafb2e`](https://github.com/openai/symphony/blob/be10a1b79df723d6d7612b5651c8522704dafb2e/SPEC.md).
+The [README at that revision](https://github.com/openai/symphony/blob/be10a1b79df723d6d7612b5651c8522704dafb2e/README.md)
+is product/demo context, not normative requirements. The spec is evolving;
+recheck the pinned revision before using this as a compatibility statement.
+
+**Hive shares the operating model, but is not Symphony-spec-conformant.**
+In particular, Hive does not expose the required `WORKFLOW.md` loader/reload,
+strict prompt-template contract, or Codex app-server runner. A vocabulary change
+cannot close those gaps. This review changes documentation only, not dispatch,
+workspace retention, permissions, or merge behavior.
+
+Verdict key:
+
+- **Satisfies**: the scoped purpose is already present; not a certification of
+  every normative clause.
+- **Small alignment**: a narrowly scoped documentation or naming improvement is
+  feasible; any underlying behavioral gap is called out separately.
+- **Diverges**: Hive intentionally uses a different contract or architecture.
+  Compatibility would require design and implementation, not a small patch.
+
+## Evidence map
+
+Local links below refer to the reviewed v5 tree. Symbol/file references are used
+rather than fragile line numbers.
+
+- **E1 — Scheduling and policy:** [architecture](../../src/docs/architecture.md),
+  especially governor and deterministic pipeline;
+  [script index](../../bin/README.md) (`run-pipeline.sh`,
+  `enumerate-actionable.sh`, `issue-classifier.sh`, `merge-gate.sh`).
+- **E2 — Tracker model:** [provider contract](../../src/docs/integrations/work-source-providers.md),
+  [`Issue` / `WorkSource`](../../src/pkg/worksource/worksource.go),
+  [`FromConfig`](../../src/pkg/worksource/factory.go),
+  [`LinearSource`](../../src/pkg/worksource/linear.go).
+- **E3 — Agents/config:** [agent configuration](../../src/docs/agent-configuration.md),
+  [`hive.yaml` example](../../src/hive.yaml.example),
+  [agent launcher](../../bin/agent-launch.sh).
+  Hive also uses app-server probes for
+  [subscription headroom](../../src/pkg/rotation/rotation.go) and
+  [model discovery](../../src/pkg/dashboard/cli_models_codex.go); those are not
+  a per-issue coding runner.
+- **E4 — Isolated execution:** [`SandboxExecutor.Run` / `prepareWorkspace`](../../src/pkg/agent/sandbox_executor.go),
+  [path/cwd tests](../../src/pkg/agent/sandbox_executor_paths_test.go).
+  This is an execution path, not a guarantee for all tmux agents.
+- **E5 — Safety:** [security self-assessment](../../src/docs/security-self-assessment.md),
+  [ACMM matrix](../../src/docs/acmm-policy-matrix.md),
+  [MITM enforcement ADR](../../src/docs/adr/0002-mitm-proxy-network-enforcement.md).
+- **E6 — Linear integration:** [work sources](../../src/docs/work-sources.md),
+  [Linear agent integration](../../src/docs/linear-agent.md),
+  [Linear factory tests](../../src/pkg/worksource/factory_linear_test.go),
+  [Linear adapter tests](../../src/pkg/worksource/linear_test.go).
+
+## Per-section verdicts
+
+Rows cover every numbered top-level section and Appendix A. Subsection ranges
+identify the contract being compared; mixed sections explicitly identify the
+part that aligns and the part that does not.
+
+| Symphony section | Verdict | Hive evidence and boundary / next action |
+| --- | --- | --- |
+| Normative language | Small alignment | Use MUST/SHOULD only for an actual contract, not marketing equivalence. No RFC 2119 conformance claim is made here. |
+| 1 — Problem statement | Satisfies (daemon workflow and observability); diverges (workspace/workflow contract) | E1/E3: persistent service dispatches coding work and exposes operator status. E4 is isolated execution, but the standard fleet is long-lived; repo-owned `WORKFLOW.md` and universal per-issue cwd are not established. |
+| 2 — Goals and non-goals (§§2.1–2.2) | Diverges | E1/E3/E5: multi-runtime fleet, dashboard, hub/spoke, and governance are core Hive concerns, whereas Symphony excludes a rich multi-tenant control plane/general distributed scheduler. Sharing polling and bounded execution does not imply identical recovery behavior. |
+| 3 — System overview (§§3.1–3.3) | Satisfies (conceptual layering); diverges (component contracts) | E1/E2/E3: policy, config, governor, source, execution, observability have analogs. Hive's YAML/config and CLI launcher do not implement the specified Workflow Loader or app-server client. |
+| 4 — Core domain model (§§4.1–4.2) | Diverges | E2: `Issue` has source, repo, external ID, priority strings, state, URL, timestamps, dependencies. It is not Symphony's all-fields-present model with opaque `id`, `native_ref`, integer priority and explicit `dispatchable`; no `thread_id-turn_id` session contract. An interoperability mapper needs identity/collision tests, not field renaming alone. |
+| 5 — Workflow specification (§§5.1–5.5) | Diverges | E3: Hive uses `hive.yaml`, agent definitions and policies, not the specified cwd-default `WORKFLOW.md`, YAML front matter, lifecycle hooks and strict Liquid-compatible prompt rendering. A workflow importer would be a separate feature. |
+| 6 — Configuration (§§6.1–6.4) | Diverges | E2/E3: typed config and secret references exist, but do not establish REQUIRED `WORKFLOW.md` watch/reapply, schema/defaults, per-tick validation, or invalid-reload semantics. Do not equate general config reload with §6.2 conformance. |
+| 7 — Orchestration state machine (§§7.1–7.4) | Diverges | E1/E3: governor kicks and agent supervision differ from one authority owning per-issue run/claim/retry maps, same-thread continuation and a one-second retry after normal exit. Hive claim coordination is not evidence of the entire reference state machine. |
+| 8 — Polling/scheduling/reconciliation (§§8.1–8.6) | Diverges | E1/E2: actionable work, holds and queue-depth cadence exist. Fixed cadence, priority/creation/identifier sort, per-state slots, exact 10-second exponential backoff, ID-refresh cancellation and terminal-workspace startup cleanup are not established as one portable contract. Symphony already gates before dispatch; calling that “none” would be incorrect. |
+| 9 — Workspace management/safety (§§9.1–9.5) | Diverges | E4: sandbox execution mounts a workspace and runs there; ordinary sandbox clones use agent/time-based paths, and run-stage worktrees are removed after execution. This differs from deterministic collision-resistant issue keys, reuse, four hook phases and terminal cleanup. Do not promise all Hive agent commands stay in per-issue directories. |
+| 10 — Agent runner protocol (§§10.1–10.7) | Diverges | E3/E4/E5: Codex execution is a CLI backend; headroom/model-discovery app-server probes are not a coding runner implementing same-thread turns, tool declarations, event/usage framing and read/silence/stall timeouts. Approval controls are documented through Hive's backend/ACMM posture, not the Symphony protocol. |
+| 11 — Tracker integration (§§11.1–11.5) | Diverges | E2/E6: `WorkSource` exposes `ListIssues`, filtering actionable items inside adapters. Symphony requires state-list plus opaque-ID full-snapshot refresh and scheduler-owned dispatchability/label filtering. Provider-specific helpers and proxy-gated writes are not host-side app-server tools; compact adapter profiles/error mappings would need additional work. |
+| 12 — Prompt construction (§§12.1–12.4) | Diverges | E3/E4: Hive assembles kick prompts and policies; no claim of strict unknown-variable/filter errors, preserved issue objects or `attempt=null` then 1-based continuation contract. Supporting those is part of a workflow adapter, not vocabulary adoption. |
+| 13 — Logging/status/observability (§§13.1–13.7) | Small alignment (terminology); diverges (interoperability) | E1/E3: dashboard, logs and cost/status visibility exist. Standardizing issue/run/session labels in documentation is cheap; exact required log fields, app-server absolute token accounting and `/api/v1/state`, issue, refresh shapes are not proven. HTTP/status are optional, but shipping Hive's dashboard does not certify §13.7. Dashboard-independent operation is separately scoped on v6 in the repository roadmap. |
+| 14 — Failure/recovery (§§14.1–14.4) | Diverges | E1/E3: supervision, stall handling and operator controls exist. Hive does not adopt Symphony's in-memory per-ticket recovery, terminal cleanup and workflow-edit intervention contract. Do not infer those semantics from process restart support. |
+| 15 — Security/operational safety (§§15.1–15.5) | Satisfies (documented trust posture); diverges (specific invariants) | E5 explicitly documents trust, ACMM, proxy enforcement and deployment-dependent confinement. E4 offers credential-free isolated execution, but is not universal enforcement of per-issue cwd/root/key invariants or host-side tracker-tool secret isolation. Hooks would require their own timeout/trust contract if adopted. |
+| 16 — Reference algorithms (§§16.1–16.6) | Diverges | E1–E4: governor/fleet paths are not ports of the startup/tick/reconcile/worker/continuation algorithms. Treat the pseudocode as input to a future compatibility mode, not a description of current Hive. |
+| 17 — Test/validation matrix (§§17.1–17.8) | Diverges | E4/E6: adapter and path tests cover useful overlaps, not the Symphony core-conformance matrix. A compatibility feature needs workflow/reload, collision, protocol, retry/reconcile and telemetry tests. Real-provider tests must report skipped when credentials are unavailable. This documentation review did not run that integration profile. |
+| 18 — Implementation checklist (§§18.1–18.3) | Diverges | Required workflow, runner and lifecycle contracts remain absent/different; optional dashboard and Linear support cannot substitute for §18.1. No conformance badge or auto-land guarantee should be published. |
+| Appendix A — SSH workers (§§A.1–A.3, optional) | Diverges | E1: hub/spoke and contributor relays address remote capacity, but are not central app-server-over-SSH ownership with per-host slots and issue workspace locality. Neither implementation of this extension nor compliance is claimed. |
+
+## Cheap vocabulary alignment adopted here
+
+“Work item”, “run attempt”, “workspace”, “handoff”, and “proof of work” are useful
+shared terms. Their boundaries matter:
+
+- A **run attempt** is execution, not proof that a ticket reached `Done`.
+- A **workspace** is a checkout or worktree; isolation claims must name the
+  execution path and enforcement layer. Workspace separation is not a sandbox.
+- A **handoff** can be a ready-for-review PR. Only authorized review/merge paths
+  may land it; this review does not increase agent authority.
+- **Proof of work** means linked, inspectable evidence, not the model's assertion
+  that checks passed. Symphony's demo names artifacts; its spec does not require
+  a walkthrough video or complexity report for every run.
+
+For a Hive PR or an outreach example, the following headings can make existing
+evidence legible without changing runtime schemas or introducing a new gate:
+
+```markdown
+## Proof of work
+- CI: link to the run/checks for this head, or state not run/pending.
+- Review: link to review feedback; do not imply approval when none exists.
+- Complexity: describe scope/risk, or state that no analysis was produced.
+- Walkthrough: link to a recording or reproducible steps, or mark not applicable.
+- Run isolation: name the execution mode/workspace and its limitations.
+- Handoff: ready for review; merge remains subject to repository policy.
+```
+
+These are recommended documentation headings, **not** newly emitted artifacts,
+a standardized machine-readable schema, or mandatory PR fields. Runtime
+protocol alignment and universal workspace guarantees are not cheap changes;
+they require a separately reviewed feature proposal.
+
+## Linear work-source decision: do, using the existing adapter
+
+The proposed stretch implementation is already in v5. Reuse
+`governor.work_source.type: linear` and `LinearSource`, rather than filing a
+second adapter implementation issue. E2/E6 document team/state selection,
+project-to-repo routing, current-cycle filtering, holds, assignment/delegation,
+pagination, secret references and tests. The target repository remains a forge
+repository; Linear supplies the work item, not a replacement for PR review.
+
+A Symphony user can configure the same Linear team/project and active states
+in Hive using the [existing configuration example](../../src/docs/integrations/work-source-providers.md#configuration-examples).
+This is a manual mapping: Hive does **not** import Symphony's `tracker.provider`
+or `WORKFLOW.md`, nor promise identical sorting, claims or state transitions.
+Use a dedicated scope or assignment filter when trying both systems so two
+orchestrators do not independently dispatch the same ticket. Validate credentials,
+routing, blocked items and handoff policy before enabling unattended work.
+
+**Defer** a Symphony workflow importer/app-server compatibility mode until there
+is concrete interoperability demand and a separately reviewed scope. That is
+not a blocker to publishing this positioning review, and no new Linear adapter
+or generic tracker-write abstraction is needed for this issue.
+
+## Outreach copy (draft, not posted)
+
+> Running the Symphony model on GitHub with deterministic merge gates:
+> Hive shares Symphony's work-driven operating model, adding a multi-runtime
+> fleet and deterministic policy around GitHub/GitLab review and merge. Linear
+> is already an available work source. Our section-by-section review explains
+> the overlap and the gaps: Hive is not a `WORKFLOW.md`/Codex app-server compatible
+> Symphony implementation. Proof of work remains inspectable CI/review evidence,
+> and landing remains subject to repository policy.
+
+Link the published [landscape comparison](../../src/docs/landscape.md#openai-symphony)
+and this review when sharing. External posting is not part of this change:
+follow [outreach anti-spam guidance](../outreach-antispam.md), and post a
+Symphony discussion only if the venue accepts this comparison. Do not advertise
+conformance, universal sandboxing, or approval-free auto-landing.

docs/landscape.md

@@ -0,0 +1,7 @@
+# Hive landscape and positioning
+
+The maintained comparison lives in [src/docs/landscape.md](../src/docs/landscape.md),
+including [OpenAI Symphony](../src/docs/landscape.md#openai-symphony).
+
+For the spec review and Linear work-source decision, see
+[Symphony spec alignment](design/symphony-spec-alignment.md).

src/docs/landscape.md

@@ -19,7 +19,7 @@ Public references: [fullsend.sh](https://fullsend.sh),
 [Fullsend runtimes](https://github.com/fullsend-ai/fullsend/blob/main/docs/runtimes.md),
 [Fullsend intent representation](https://github.com/fullsend-ai/fullsend/blob/main/docs/problems/intent-representation.md).
 
-Fullsend is the most directly comparable open-source project. Its public README
+Fullsend is a closely comparable open-source project. Its public README
 positions it as autonomous agentic software development for Git-hosted
 organizations, including GitHub, GitLab, and Forgejo. Its docs emphasize a
 repo-visible coordination model: target repositories carry `.fullsend/`
@@ -52,6 +52,43 @@ infrastructure. Hive is a better fit when operators need live fleet visibility,
 multiple runtimes, graduated autonomy, hub-managed spokes, contributor compute,
 or network-level enforcement independent of agent runtime hooks.
 
+## OpenAI Symphony
+
+Reviewed against [OpenAI Symphony](https://github.com/openai/symphony) at
+[`be10a1b`](https://github.com/openai/symphony/tree/be10a1b79df723d6d7612b5651c8522704dafb2e).
+Public references: [README](https://github.com/openai/symphony/blob/be10a1b79df723d6d7612b5651c8522704dafb2e/README.md),
+[Draft v1 SPEC.md](https://github.com/openai/symphony/blob/be10a1b79df723d6d7612b5651c8522704dafb2e/SPEC.md).
+Symphony is Apache-2.0 licensed and describes its Elixir reference implementation
+as an engineering preview for trusted environments. Its demo monitors Linear,
+runs isolated coding agents, and presents proof of work (CI status, review
+feedback, complexity analysis, and walkthrough videos) before accepted PRs land.
+Those demo artifacts and auto-landing are **not** mandatory spec requirements:
+a successful spec run can stop at a human-review handoff.
+
+Hive applies the Symphony operating model—manage work rather than supervise
+every coding turn—to GitHub/GitLab-native projects, with deterministic policy
+gating in front of the agent. This is a positioning analogy, **not** a claim
+that Hive implements Symphony's `WORKFLOW.md` or Codex app-server contracts.
+
+| Dimension | Symphony | Hive |
+| --- | --- | --- |
+| Work source | Linear in the demo; the current spec defines a provider-neutral tracker adapter. | GitHub/GitLab forge workflows; primary planning adapters include GitHub Issues/Projects, Linear, and Jira. |
+| Pre-agent gating | Config preflight, active/terminal states, required labels, adapter dispatchability, claims, and concurrency checks (spec §§6–8). | Deterministic shell enumeration/classification/merge eligibility before a kick, plus ACMM and network-level write enforcement. |
+| Agents | Codex app-server is the specified runner protocol. | Multiple CLI backends, including Claude, Copilot, Gemini, Goose, and Codex; confinement depends on backend and deployment. |
+| Scale model | Per-issue persistent workspace, bounded concurrent runs, reconciliation, continuation, and retry. | Queue-depth-driven cadence, long-lived agents, isolated execution paths, hub/spoke, and convergence audits. |
+| Packaging | Language-neutral draft specification and experimental Elixir reference implementation. | Go runtime and supporting scripts, Compose/Quadlet deployment, dashboard, and contributor relay. |
+
+Choose Symphony when a repo-owned `WORKFLOW.md`, the Codex app-server contract,
+and per-ticket workspace lifecycle are the desired integration surface. Choose
+Hive when fleet operations, multiple runtimes, forge-native review/merge policy,
+and graduated autonomy are central. Neither tool's workspace isolation alone
+constitutes a sandbox.
+
+See the [section-by-section alignment review](../../docs/design/symphony-spec-alignment.md)
+for gaps and intentional divergences, the existing
+[Linear work source](work-sources.md), and
+[work-source provider contract](integrations/work-source-providers.md).
+
 ## Single-agent and service-oriented tools
 
 ### GitHub Copilot coding agent
@@ -85,6 +122,8 @@ multi-agent fleet operation.
 - Choose **GitHub Copilot coding agent** when you need the quickest hosted path
   for GitHub issues and do not need a separate fleet governor or custom policy
   plane.
+- Choose **Symphony** when you want a spec-first, repo-owned `WORKFLOW.md`
+  and Codex app-server orchestration with per-ticket persistent workspaces.
 - Choose **Fullsend-style tooling** when you have a small number of repos, want
   GitHub Actions or native CI to be the execution substrate, prefer repo-visible
   `.fullsend/` configuration, and want little or no always-on infrastructure.