PaperClipAI/docs/specs/external-task-protocol.md

# Paperclip External Task Protocol Specification

Status: Draft v1 (provider-agnostic)

Purpose: Define the protocol by which Paperclip interoperates with external task managers (Linear,
Jira, Asana, Notion, Trello, GitHub Issues, and others) so that external tasks can drive Paperclip
agent work and Paperclip work is visible in the external tool, without requiring an external user
account for every Paperclip agent.

## Normative Language

The key words `MUST`, `MUST NOT`, `REQUIRED`, `SHOULD`, `SHOULD NOT`, `RECOMMENDED`, `MAY`, and
`OPTIONAL` in this document are to be interpreted as described in RFC 2119.

`Implementation-defined` means the behavior is part of the implementation contract, but this
specification does not prescribe one universal policy. Implementations MUST document the selected
behavior.

Terminology in this document:

- `Provider` — an external task manager product (Linear, Jira, Asana, Notion, Trello, GitHub
  Issues, ...).
- `Connector` — an implementation of this protocol for one provider, hosted in the Paperclip
  plugin runtime.
- `External task` — a task record that lives in the provider.
- `Paperclip issue` — the native Paperclip task record.
- `Host` — the Paperclip control plane: companies, agents, issues, checkout, heartbeat runs,
  execution workspaces, budgets, approvals, blockers, issue documents, and work products.

## 1. Problem Statement

Teams already run their work in external task managers. Paperclip runs companies of agents. Today
these worlds only meet through manual copy/paste: a human reads a Linear issue, rewrites it as a
Paperclip issue, and later rewrites the outcome back into Linear.

This protocol defines the contract that lets an external task manager act as a **task source and
collaboration surface** for a Paperclip company, while Paperclip remains the **execution and
governance control plane**.

The protocol solves four interoperability problems:

- It defines one normalized task model so each connector translates provider payloads once, at the
  edge, instead of leaking provider-specific shapes into agent prompts and core logic.
- It defines how an external task becomes (or links to) exactly one Paperclip issue, with
  idempotent sync state that survives retries, webhook replays, and restarts.
- It defines how external assignment routes to Paperclip agents without creating a provider user
  per agent.
- It defines which writes flow back to the provider, under what policy, and with what provenance,
  so sync is predictable rather than chatty or destructive.

Important boundary (inherited from OpenAI Symphony, see Section 3.3):

- The connector is a tracker reader, sync engine, and routing layer.
- Provider writes (state transitions, comments, links) are explicit, policy-bound connector
  operations — never hidden side effects of core host logic.
- A successful agent run can end at a workflow-defined handoff state (for example review), not
  necessarily the provider's `Done`.

## 2. Goals and Non-Goals

### 2.1 Goals

- Let an external task manager act as a task source: active external tasks create or wake
  Paperclip issues under configured policy.
- Keep one normalized external-task model across all providers, with provider-specific data
  carried in an envelope, not in the core model.
- Route external assignment intent to Paperclip agents through deterministic, configurable rules.
- Reuse Paperclip's existing execution semantics — checkout as claim, heartbeat runs, execution
  workspaces, retries and recovery — as a Symphony-compatible orchestration profile.
- Make outbound writes explicit, policy-bound, idempotent, and attributable.
- Detect conflicts instead of silently overwriting either side.
- Give operators observability: link state, sync health, cursors, queues, retries, and conflicts.
- Keep connectors implementable as plugins, without private host internals.

### 2.2 Non-Goals

- Replacing the Paperclip board with a clone of any provider's UI.
- Real-time field-level collaborative editing between Paperclip and a provider.
- A generic workflow engine or a universal schema covering every provider feature. Provider
  features beyond the normalized model stay in the provider envelope.
- Creating a provider user account per Paperclip agent (supported as an OPTIONAL mapping, never
  required).
- Letting external systems bypass Paperclip governance: checkout, budgets, approvals, blockers,
  execution policies, and company boundaries remain host-owned.
- Migrating data: this is a sync protocol, not an importer/exporter for full historical fidelity.

## 3. System Overview

### 3.1 Main Components

1. `Task Source Adapter`
   - Provider client owned by the connector.
   - Fetches candidate external tasks and task states.
   - Normalizes provider payloads into the `ExternalTask` model.
   - Performs provider writes when policy allows.

2. `Task Link Store`
   - Persists the 1:1 association between an external task and a Paperclip issue.
   - Owns sync state: snapshots, fingerprints, cursors, status.
   - MUST be stored in plugin state/entities first; MAY be promoted to core schema once at least
     two connectors prove the model (see Section 16.4).

3. `Inbound Sync Engine`
   - Consumes webhooks and poll results.
   - Creates/updates Paperclip issues and imports comments with provenance.
   - Runs scheduled reconciliation to repair drift.

4. `Routing Engine`
   - Resolves external assignment intent into a Paperclip assignee using the ordered rule
     pipeline in Section 8.

5. `Execution Bridge`
   - Maps tracker-driven work onto host execution: issue checkout (claim), heartbeat runs,
     execution workspaces, retry/recovery. Defined as the Symphony profile in Section 9.

6. `Outbound Write Engine`
   - Applies the write policy in Section 10: progress comments, status projection, backlinks,
     artifact/PR links.

7. `Conflict Queue`
   - Records detected conflicts and exposes resolution actions (Section 11).

8. `Health Surface`
   - Operator-visible connector status: last webhook, last poll, last reconcile, cursor positions,
     queue depth, retry counts, current errors (Section 12).

### 3.2 Protocol Layers

The protocol is layered. A connector MAY implement lower layers without higher ones.

1. `Layer 1 — Task Source Adapter` (REQUIRED)
   - Normalized read access to provider tasks. Sufficient for browse/import UX.

2. `Layer 2 — Task Link` (REQUIRED)
   - Durable external-task ↔ Paperclip-issue association with sync state.

3. `Layer 3 — Execution Orchestration, Symphony Profile` (RECOMMENDED)
   - Active external states drive Paperclip issue creation/wake; Paperclip checkout/run/retry
     semantics are projected back as claim state.

4. `Layer 4 — Write and Sync Policy` (RECOMMENDED)
   - Policy-bound outbound writes and two-way comment/status sync.

A connector that implements Layers 1–3 for read-driven execution is a **Symphony-compatible task
source** (Section 9.6).

### 3.3 Relationship to OpenAI Symphony

OpenAI Symphony specifies a service in which an issue tracker drives isolated, autonomous coding
agent runs: normalized tracker issues, active/terminal state mapping, claim/run/retry/release
lifecycle, per-issue workspaces, repository-owned workflow policy (`WORKFLOW.md`), and
operator-visible observability.

This protocol deliberately defers to Symphony's semantics wherever Symphony solves the same
problem, and maps them onto existing host primitives:

| Symphony concept | This protocol |
| --- | --- |
| Tracker client + normalized issue | Task Source Adapter + `ExternalTask` (Section 5) |
| Active / terminal states | Connector state mapping (Section 7.2) |
| Claim | Paperclip issue checkout + execution lock (Section 9.2) |
| Running map / live session | Heartbeat runs + issue liveness state (Section 9.3) |
| Retry queued | Host retry/recovery + scheduled wakes (Section 9.3) |
| Released | Issue terminal/review/blocked, or external task no longer active (Section 9.3) |
| Per-issue workspace | Execution workspace / worktree (Section 9.4) |
| `WORKFLOW.md` | Workflow policy document (Section 9.5) |
| Tracker writes via agent tools, not orchestrator | Outbound Write Engine + connector tools (Section 10.1) |
| Status surface | Issue/run/connector health UI (Section 12) |

Where Symphony is intentionally narrow — single repository, coding agents only, one tracker, no
multi-tenant control plane — this protocol extends it with company scoping, multi-agent routing,
governance gates, issue documents/work products, and two-way sync policy. Section 9.6 defines what
a connector MUST do to claim Symphony-profile conformance. Appendix B gives a section-by-section
crosswalk.

### 3.4 Core vs Connector Boundary

The host MUST own:

- Company scoping and authorization of every mutation.
- Issue checkout, execution locks, heartbeat invocation, and execution workspace lifecycle.
- Budget, approval, blocker, and execution-policy enforcement.
- Issue documents and work products.
- The normalized protocol types, once validated (shared SDK package).

Connectors MUST own:

- Provider authentication and webhook verification.
- Provider polling, pagination, and cursor management.
- Provider-specific state mapping and the provider envelope.
- All provider writes (comments, transitions, fields, links).
- Provider-specific setup, settings, and issue-detail UI.

A connector MUST perform all Paperclip issue/comment/status mutations through the capability-gated
plugin host clients (for example, `ctx.issues`) with plugin attribution. It MUST use `ctx.entities`
or `ctx.state` for connector-owned link and cursor data, and secret references for provider
credentials. A connector MUST NOT write host tables directly.

## 4. Core Domain Model

Field names use camelCase, matching Paperclip API conventions. (Symphony uses snake_case; the
crosswalk in Appendix B maps equivalent fields.)

### 4.1 Entities

#### 4.1.1 ExternalTask

Normalized external task record produced by the Task Source Adapter. This is the only shape the
host, routing engine, and prompt/task-packet rendering may depend on.

Fields:

- `providerKey` (string)
  - Stable provider identifier: `linear`, `jira`, `asana`, `notion`, `trello`, `github_issues`.
- `externalId` (string)
  - Stable provider-internal ID. Used for lookups and link keys.
- `externalKey` (string or null)
  - Human-readable key where the provider has one (example: `ABC-123`). Null for providers
    without keys (Trello, Notion).
- `title` (string)
- `description` (string or null)
  - Normalized to Markdown on a best-effort basis; lossy conversions MUST be noted in the
    envelope.
- `state` (object)
  - `name` (string) — provider state/lane name.
  - `category` (enum) — normalized category: `backlog`, `active`, `review`, `blocked`, `terminal`
    (Section 7.2).
- `priority` (integer or null)
  - Normalized 0–4, lower is more urgent. Non-mappable provider scales become null with the raw
    value preserved in the envelope.
- `assignees` (list of external actor refs)
- `labels` (list of strings)
  - Trimmed, lowercased.
- `blockedBy` (list of external task refs: `{externalId, externalKey, state}`)
  - Derived from provider relations where supported; empty otherwise.
- `url` (string or null)
- `branchName` (string or null)
  - Provider-supplied branch metadata if available.
- `dueAt`, `createdAt`, `updatedAt` (timestamps or null)
- `revision` (string or null)
  - Provider revision/version/etag when available; used for conflict detection.
- `envelope` (object)
  - Provider-specific payload (Section 4.1.2). Opaque to the host.

#### 4.1.2 ProviderEnvelope

Provider-specific data that does not generalize. Carried alongside the normalized model, persisted
with the task link, surfaced in provider-specific UI, and available to connector tools. The host
core MUST NOT branch on envelope contents.

Representative envelope content per provider is listed in Appendix A.

#### 4.1.3 TaskLink

The durable 1:1 association between one external task and one Paperclip issue.

Fields:

- `id` (string)
- `providerKey` (string)
- `connectorInstanceId` (string)
  - One installed connector configuration (a provider MAY be installed multiple times per
    company, e.g. two Jira sites).
- `companyId`, `projectId`, `goalId`, `issueId` (strings; `issueId` is the linked Paperclip issue)
- `handoffHistory` (list of `{issueId, endedAt, cause}`; empty for a link that has never moved)
  - Prior Paperclip issue associations retained when reopened work is handed to a follow-up.
- `externalWorkspaceId`, `externalProjectId` (strings or null)
  - Provider container coordinates (team/project/board/database).
- `externalTaskId`, `externalKey`, `externalUrl`
- `originSide` (enum: `paperclip`, `external`, `manual_link`)
  - Which side created the pairing.
- `syncMode` (enum, Section 4.2.1)
- `runMode` (enum, Section 4.2.2)
- `fieldPolicy` (map field → owner, Section 4.1.4)
- `baseSnapshot` (object)
  - Last agreed projected state of both sides; the three-way merge base for conflict detection.
- `lastExternalRevision` (string or null)
- `lastPaperclipFingerprint` (string or null)
  - Hash of the last Paperclip-side state this connector projected outbound.
- `lastInboundAt`, `lastOutboundAt`, `lastReconcileAt` (timestamps or null)
- `status` (enum, Section 4.2.3)
- `statusDetail` (string or null)
  - Human-readable explanation for `conflict`, `error`, `paused`.

Invariants:

- A `(connectorInstanceId, externalTaskId)` pair MUST map to at most one active link.
- An `issueId` MUST appear in at most one active link per connector instance, and SHOULD appear in
  at most one active link overall; cross-connector double-linking is implementation-defined and
  MUST be surfaced in UI when allowed.
- Every link MUST belong to exactly one `companyId`, resolved at link creation, before any
  mutation on either side.

#### 4.1.4 FieldOwnershipPolicy

Per-field ownership controlling sync direction and conflict classification.

- Owners: `external`, `paperclip`, `shared`.
- Coverable fields (minimum): `title`, `description`, `state`, `priority`, `labels`, `assignee`,
  `dueAt`.
- Default policy (RECOMMENDED): `title`/`description`/`priority`/`labels`/`dueAt` owned by
  `external` for links with `originSide=external` (and by `paperclip` when
  `originSide=paperclip`); `state` is `shared` and mediated by Section 7.4 and Section 10.3;
  `assignee` is never directly synced — it flows through routing (Section 8).
- Writes from the non-owning side to an owned field MUST NOT be applied silently; they produce a
  conflict entry (Section 11) or are dropped per policy, and the choice MUST be visible in link
  health.

#### 4.1.5 RoutingRule

One rule in the connector's ordered routing pipeline (Section 8).

Fields:

- `order` (integer)
- `kind` (enum: `default_route`, `custom_field`, `label`, `state_lane`, `comment_command`,
  `user_mapping`)
- `match` (object, kind-specific: field id + value pattern, label pattern, lane/state name,
  external user id)
- `target` (object)
  - `agentId` (string) or `routingAlias` (string, e.g. `triage`, `qa`, resolved against company
    configuration).
- `enabled` (boolean)

#### 4.1.6 ExternalActor

Provenance identity for inbound content.

Fields:

- `providerKey`
- `externalUserId` (string)
- `displayName` (string)
- `mappedUserId` (string or null) — Paperclip user, if mapped.
- `mappedAgentId` (string or null) — Paperclip agent, if explicitly mapped (OPTIONAL feature).
- `isConnectorServiceAccount` (boolean)
  - True when the actor is the connector's own provider identity. REQUIRED for echo suppression
    (Section 10.4).

#### 4.1.7 SyncCursor

Per-connector-instance incremental sync state.

Fields:

- `scope` (string) — e.g. `tasks:<externalProjectId>`, `comments:<externalTaskId>`.
- `cursor` (string) — provider-opaque pagination/delta token or high-water-mark timestamp.
- `updatedAt` (timestamp)

Cursors MUST be persisted transactionally with the effects of the page they describe, so a crash
between "apply page" and "save cursor" re-applies idempotently rather than skipping.

#### 4.1.8 ConnectorHealth

Operator-visible runtime state per connector instance.

Fields:

- `lastWebhookAt`, `lastPollAt`, `lastReconcileAt` (timestamps or null)
- `webhookVerified` (boolean)
- `queueDepth` (integer) — pending inbound events.
- `retryCount` (integer) — currently scheduled retries.
- `conflictCount` (integer) — open conflict entries.
- `lastError` (object or null: `{category, message, at}`)
- `status` (enum: `healthy`, `degraded`, `error`, `paused`)

### 4.2 Enumerations

#### 4.2.1 `syncMode`

Per-link data flow direction:

- `import_only` — external → Paperclip only.
- `export_only` — Paperclip → external only.
- `bidirectional` — both directions under `fieldPolicy`.
- `observer` — read and display external state; mutate neither side.
- `disabled` — link retained, no sync.

#### 4.2.2 `runMode`

Per-link execution posture:

- `paperclip_controlled` — Paperclip governance decides when agents run; external state changes
  inform but do not command execution.
- `symphony_compatible` — active external states create/wake Paperclip work automatically per
  Section 9; the external tracker effectively drives dispatch.
- `external_observer` — no execution coupling; link exists for visibility only.

#### 4.2.3 Link `status`

- `pending` — link created, first sync not yet completed.
- `healthy` — last sync succeeded, no open conflicts.
- `conflict` — one or more unresolved conflict entries.
- `error` — last sync attempt failed; retry scheduled or exhausted.
- `paused` — operator suspended sync.
- `unlinked` — association severed; record retained for audit.

### 4.3 Stable Identifiers and Normalization Rules

- `External Task ID` — use for provider lookups and link keys. Never display-only keys.
- `External Key` — use for human-readable logs, comments, and UI.
- `Link key` — `(connectorInstanceId, externalTaskId)`.
- `Idempotency key` for inbound effects — `(connectorInstanceId, externalTaskId, eventId)` where
  the provider supplies event IDs, else a content hash of the normalized change. Replayed webhooks
  MUST NOT duplicate issues or comments.
- `Idempotency key` for outbound effects — `(linkId, effectKind, paperclipSourceId)` (e.g. the
  Paperclip comment ID being mirrored). Retried jobs MUST NOT double-post.
- State names compare after trim + lowercase.
- Labels normalize to trimmed, lowercased strings.
- Timestamps normalize to ISO-8601 UTC.

## 5. Task Source Adapter Contract

### 5.1 REQUIRED Operations

A connector MUST implement:

1. `listCandidateTasks(scope, cursor) -> {tasks: ExternalTask[], cursor}`
   - Return tasks in configured containers (team/project/board/database), filtered to configured
     states where the provider supports server-side filtering, paginated.

2. `getTask(externalTaskId) -> ExternalTask`

3. `getTaskStates(externalTaskIds) -> {externalTaskId -> state}`
   - Batched state refresh for reconciliation (Section 7.1.3) and run-eligibility checks
     (Section 9.3).

4. `listComments(externalTaskId, cursor) -> {comments: ExternalComment[], cursor}`
   - Each comment carries `externalCommentId`, `ExternalActor`, body (Markdown best-effort),
     timestamps.

5. `verifyWebhook(request) -> VerifiedEvent | reject`
   - Validate provider signatures/secrets where the provider supports them (Section 14.2). For
     providers without signed webhooks, the connector MUST treat webhook payloads as untrusted
     hints and confirm by API read-back before applying effects.

### 5.2 OPTIONAL Write Operations and Capability Declaration

Write operations are OPTIONAL per connector and gated by policy (Section 10):

- `createTask(projection) -> ExternalTask`
- `updateTaskState(externalTaskId, targetStateName)`
- `postComment(externalTaskId, body, attribution) -> externalCommentId`
- `setFields(externalTaskId, partial fields per fieldPolicy)`
- `setBacklink(externalTaskId, paperclipUrl)`
  - Via link field, custom field, or pinned comment — provider-dependent.

A connector MUST declare a static capability set (readable by host UI) enumerating which
operations it implements, which state categories it can map, whether webhooks are signed, and
which routing rule kinds it supports. Host UX MUST degrade gracefully (hide actions, explain
gaps) based on declared capabilities.

### 5.3 Normalization Requirements

- Adapter output MUST match Section 4.1.1. Provider payload fields with no normalized home go in
  the envelope.
- State category mapping (Section 7.2) is part of adapter configuration, not code, wherever the
  provider has user-defined workflows (Jira, Linear, Trello lists, Notion selects).
- Rich text MUST convert to Markdown best-effort; the envelope SHOULD retain the source format
  reference for lossless round-trips where the connector supports them.
- Person references in body text SHOULD be converted to plain display names; raw provider mention
  syntax MUST NOT leak into Paperclip issue bodies where it could be misparsed as Paperclip
  mentions.

### 5.4 Error Handling Contract

RECOMMENDED error categories:

- `provider_auth` (expired/invalid credentials)
- `provider_rate_limited` (with retry-after when available)
- `provider_request` (transport failures)
- `provider_status` (non-2xx)
- `provider_payload` (unparseable/unknown payload)
- `cursor_invalid` (provider rejected or lost the cursor)
- `webhook_signature` (verification failure)

Engine behavior on adapter errors:

- Candidate fetch failure: log, mark health `degraded`, skip this tick; never tear down existing
  links or active work.
- State refresh failure during reconciliation: keep current link state; do not release claims or
  stop runs on missing data (matches Symphony's reconciliation posture).
- `cursor_invalid`: fall back to a bounded full re-list with idempotent re-apply; never wipe and
  re-import.
- `provider_rate_limited`: back off honoring provider guidance; webhook intake continues to queue.

## 6. Task Link Lifecycle

### 6.1 Link State Machine

```
create                         -> pending
pending  -- first sync ok      -> healthy
healthy  -- sync failure       -> error
error    -- retry ok           -> healthy
healthy  -- conflict detected  -> conflict
conflict -- resolved           -> healthy
any state -- operator pause    -> paused (resume returns to previous state)
any state -- unlink            -> unlinked (terminal; record retained)
```

Transitions MUST be recorded with timestamps and causes in the link record or its audit trail.

### 6.2 Link Creation Paths

1. `Import` (`originSide=external`)
   - An external task is selected (manually, or automatically under `runMode=symphony_compatible`
     state mapping) and a Paperclip issue is created from its projection.
   - The created issue MUST carry: source attribution (provider, external key, URL), the
     normalized description, and routing-resolved assignee (Section 8).

2. `Export` (`originSide=paperclip`)
   - A Paperclip issue is projected into the provider via `createTask`.
   - REQUIRED only for connectors declaring write capability.

3. `Manual link` (`originSide=manual_link`)
   - Operator pairs an existing external task with an existing Paperclip issue.
   - The connector MUST compute an initial `baseSnapshot` from both sides and surface immediate
     divergence as conflicts rather than picking a winner.

### 6.3 Deduplication

Before creating an issue or external task, the connector MUST check, in order:

1. Active link with the same `(connectorInstanceId, externalTaskId)`.
2. Paperclip backlink already present on the external task (custom field/comment marker).
3. External URL/key reference already present on a Paperclip issue in the same company.

Title-similarity matching MAY be used to *warn* in import UX; it MUST NOT silently merge.

### 6.4 Unlink and External Deletion Semantics

- Unlink severs sync but MUST NOT delete either side's record.
- When an external task is deleted/archived: the connector MUST NOT delete or cancel the Paperclip
  issue. Default behavior: mark the link `conflict` (`statusDetail: external task deleted`),
  comment on the Paperclip issue, and let the assignee/operator decide. `import_only` links with
  no Paperclip-side activity MAY auto-unlink.
- When a Paperclip issue is cancelled/deleted: outbound policy decides whether to comment and/or
  transition the external task; the connector MUST NOT delete the external task unless an
  operator explicitly invokes a delete capability.

## 7. Inbound Synchronization (External → Paperclip)

### 7.1 Event Channels

A connector MUST implement at least one push or pull channel, and MUST implement reconciliation.

#### 7.1.1 Webhooks

Webhooks are RECOMMENDED where the provider offers them. They are verified per Section 5.1(5).
Events are queued, deduplicated by idempotency key, and applied in per-task order. Webhooks are
treated as *hints*: on any doubt, re-read via the adapter.

#### 7.1.2 Polling

Polling uses cursor-based incremental listing on a configured cadence. It is REQUIRED when
webhooks are unavailable or unverified, and RECOMMENDED as a backstop even with webhooks.

#### 7.1.3 Reconciliation

Reconciliation is REQUIRED. A scheduled job compares linked tasks' current provider state against
`baseSnapshot` and the linked issue. It repairs missed events, detects deletions or archivals, and
refreshes health timestamps. Reconciliation MUST be rate-bounded and incremental (cursor or rolling
window). It MUST NOT re-read every link on every run for large installations.

### 7.2 State Mapping

Each connector instance MUST carry an explicit mapping from provider states/lanes to the
normalized categories:

- `backlog` — visible, not requesting execution.
- `active` — requesting execution (Symphony's "active states").
- `review` — provider-side human review/handoff.
- `blocked` — provider-side blocked indication, where representable.
- `terminal` — done/cancelled/archived.

Mapping rules:

- Mapping is configuration, validated at setup against live provider workflow metadata where
  available.
- Unmapped states MUST be treated as `backlog` (inert) and reported in health, never guessed.
- Category transitions drive issue effects per Section 7.4 and run effects per Section 9.3.

### 7.3 Comment Import and Provenance

- Imported comments MUST carry `ExternalActor` provenance and a deep link to the external comment
  where the provider supports it.
- Imported comment content is **untrusted input**: it MUST be clearly attributed in the issue
  thread, MUST NOT be interpreted as Paperclip system/agent instructions, and mention-like syntax
  MUST NOT trigger Paperclip mention semantics except via the strict command path (Section 8.2).
- Whether an imported comment wakes the issue assignee is link policy (`wakeOnExternalComment`,
  default true for `symphony_compatible`, false for `observer`).
- Comments authored by the connector's own service account MUST be suppressed on import
  (Section 10.4).

### 7.4 External State Transitions Against Paperclip Work

When the external task changes category:

- `backlog -> active`: create or wake per `runMode` (Section 9.3).
- `active -> backlog` or `active -> blocked`: the connector SHOULD surface this on the issue; under
  `symphony_compatible` it MUST make the issue ineligible for new tracker-driven dispatch and
  MUST request stop of a tracker-driven run only when the plugin host declares an issue-scoped
  run-stop capability (Section 9.3). Without that capability, it records a health warning and lets
  the active run finish. It MUST NOT pause the whole agent because that could stop unrelated work.
  Paperclip-native obligations (approvals in flight, blockers) are unaffected.
- `* -> terminal` while the Paperclip issue is active (checked out, running, in review, or carrying
  unresolved blockers/approvals): default is a **conflict**, not silent closure. The issue gets a
  comment naming the external actor and transition; the link enters `conflict` until an agent or
  operator resolves it. Auto-close MAY be enabled per link policy only when no active run, no
  pending review/approval, and no blockers exist.
- `terminal -> active` (reopen): if the linked issue is terminal, policy chooses between creating a
  follow-up Paperclip issue linked to the same external task (RECOMMENDED default) or reopening,
  subject to host rules for resuming closed issues. The connector MUST create or find the follow-up
  with a stable idempotency key while the existing link remains active. After the follow-up is
  durably identified, it retargets that same `TaskLink` record to the follow-up and appends the old
  `issueId` to `handoffHistory` in one record update. On the current plugin SDK, this is one
  `ctx.entities.upsert` of the entity keyed by the external task, not an unlink plus a second entity
  write; inbound processing is already serialized per task (Section 7.1.1). A crash before the
  upsert leaves the old link active, and a retry reuses the idempotent follow-up. A crash after it
  leaves the retargeted link active. This preserves the link-key invariant in Section 4.1.3 without
  requiring a multi-record transaction, while `handoffHistory` retains the original association
  for audit.

External transitions MUST NOT directly set Paperclip issue status; they translate into host-level
requests that respect checkout, approvals, blockers, budget stops, and execution policy.

## 8. Agent Routing (Assignment Without External Agent Users)

External assignment intent resolves to a Paperclip assignee through an ordered pipeline. The first
matching enabled rule wins. Routing runs at import, and again whenever external assignment intent
changes (assignee change, label/field change, lane move, command comment).

### 8.1 Routing Pipeline

1. `comment_command` — strict slash command in an external comment (Section 8.2).
2. `custom_field` — provider custom field naming an agent (example: `Paperclip Agent = CodexCoder`).
3. `label` — namespaced label (example: `pc:agent/codexcoder`, `pc:route/qa`).
4. `state_lane` — provider state/lane mapped to a route (example: Trello list `Paperclip: QA`).
5. `user_mapping` — explicit external-user → agent mapping table (OPTIONAL; for teams that choose
   to create provider users for agents).
6. `default_route` — connector/project default (example: all imported tasks go to a triage agent
   or the CTO agent).

Requirements:

- Routing MUST resolve before the issue is created; every imported issue has an assignee.
- If no rule matches and no default route exists, the connector MUST assign the configured triage
  fallback and post a visible "unresolved routing" comment on both sides (external side only if
  write policy allows). Import MUST NOT be dropped silently.
- Routing targets are validated against the live company agent registry at apply time; routes to
  missing/paused agents fall through to triage with a health entry.
- Re-routing an issue that is checked out MUST NOT force-reassign; it posts a handoff request
  comment for the current owner (host reassignment rules apply).

### 8.2 Strict Comment Commands

Comment commands give external users explicit control without new UI in the provider.

- Syntax: line-anchored `/paperclip <verb> [args]`. Minimum verbs: `assign <agent>`,
  `status`, `pause`, `resume`. Connectors MAY add verbs; all verbs MUST be listed in capability
  metadata.
- Parsing MUST be deterministic connector code. An LLM MUST NOT infer intent from free text.
- The connector MUST reply (externally, if writes allowed; on the Paperclip issue otherwise) with
  the command outcome, including rejections (unknown agent, not permitted).
- Command authorization is implementation-defined but MUST be documented (e.g. any provider
  member vs. mapped users only).

### 8.3 Identity Model

- Paperclip agents MUST NOT be required to exist as provider users.
- Outbound writes use one connector service account per connector instance (Section 10.4), with
  agent attribution carried in message content ("CodexCoder via Paperclip").
- `user_mapping` rules MAY map specific provider users to Paperclip users (for `assign it back to
  me` flows) and to agents, but every such mapping is explicit configuration.

## 9. Execution Orchestration: Symphony Profile

This section defines how tracker-driven execution maps onto host primitives. It applies to links
with `runMode=symphony_compatible`; `paperclip_controlled` links use only Sections 9.4–9.5 advice.

### 9.1 Dispatch Model

Symphony's poll-tick loop becomes, in Paperclip:

1. Inbound sync (webhook/poll/reconcile) maintains link + normalized state.
2. For each link whose external category is `active`, the connector first moves a linked `backlog`
   issue to `todo` through the host issue client, subject to normal host transition rules. A
   `backlog` issue is not wakeable and MUST NOT receive a wake request directly.
3. When the linked issue is `todo`, not blocked, and not awaiting approval, the connector wakes the
   assignee through `ctx.issues.requestWakeup`.
4. Host heartbeat scheduling — not the connector — decides actual run start, respecting company
   concurrency, budget, and execution policy. The connector MUST NOT spawn agent processes
   itself.

Bounded concurrency, dispatch ordering by priority, and per-issue serialization are host
responsibilities; the connector's job ends at "make the issue actionable and wake the right
agent."

### 9.2 Claim Semantics

- Paperclip issue checkout is the claim. One agent owns an issue at a time; checkout conflicts
  (409) mean the issue is already claimed.
- The connector MUST treat checkout state as authoritative and MUST NOT maintain a parallel claim
  registry for linked issues.
- Claim state SHOULD be projected outbound (Section 10.3) so external users can see that an agent
  has picked the task up.

### 9.3 Run Lifecycle, Retry, Release

Host-side equivalents of Symphony's run-attempt machine:

- `Running` — an active heartbeat run exists for the issue's assignee on this issue.
- `RetryQueued` — host recovery/scheduled wake exists (failed run recovery, blocked-resume,
  scheduled continuation).
- `Released` — issue reached terminal/review/blocked state, or the external task left `active`.

Profile requirements:

- When the external task leaves `active` during tracker-driven work, the connector MUST mark the
  link state accordingly and stop issuing new connector wake requests. If the plugin host declares
  an issue-scoped run-stop capability, the connector MUST use it for the active issue run. It MUST
  NOT kill processes directly or approximate issue-scoped stop by pausing the assigned agent.
- The current plugin SDK does not expose an issue-scoped run-stop operation. On that host version,
  a connector MUST record `issue_run_stop_unsupported`, let the active run finish, and MUST NOT
  claim full Symphony profile conformance. Layers 1, 2, and 4 remain implementable.
- Failed runs follow host retry/recovery; the connector MUST NOT re-wake an issue in a tight loop
  (wake requests for the same link MUST be debounced, RECOMMENDED minimum 60s).
- A successful run that ends at `in_review`/handoff is a valid terminal outcome for the
  tracker-driven cycle (mirrors Symphony's `Human Review` boundary); the connector projects
  `review`, it does not force `terminal`.

### 9.4 Workspaces

Per-issue isolation is provided by host execution workspaces/worktrees keyed by issue. Follow-up
issues can inherit the source issue's project and workspace strategy
(`inheritExecutionWorkspaceFromIssueId`), but each gets its own workspace; code carries over through
pushed branches, not a shared checkout. The connector never manages filesystem workspaces.

### 9.5 Workflow Policy

Symphony's repository-owned `WORKFLOW.md` maps to a layered policy lookup for rendering the task
packet (Section 9.5.1) and run guidance:

1. Paperclip project workflow document (RECOMMENDED MVP form).
2. Repository `WORKFLOW.md` discovered in the project workspace (OPTIONAL, code projects).
3. Connector instance defaults.

Precedence and safety:

- Workflow policy is versioned project policy. It MAY shape prompts, validation steps, and
  handoff targets.
- Workflow policy MUST NOT override host system/company/agent instructions, governance gates, or
  this protocol's invariants. It is additive guidance, lowest precedence.

#### 9.5.1 Task Packet Rendering

Tracker-originated work MUST reach the agent as a rendered task packet, not raw provider text:

- Inputs: normalized `ExternalTask`, link metadata (backlink URL, sync/run mode), workflow policy,
  attempt/continuation context.
- The packet MUST mark external content as externally-authored untrusted input.
- The packet MUST include the external key/URL so agents can reference the source task in
  comments and PRs.
- Rendering MUST be strict: missing required variables fail the dispatch with a health entry
  rather than emitting a partial prompt.

### 9.6 Symphony Profile Conformance

A connector MAY claim "Symphony-compatible task source" when:

- Layers 1–3 are implemented.
- Active/terminal state mapping is explicit configuration (Section 7.2).
- Active external tasks create/wake issues without manual import, under operator-enabled policy.
- Checkout-as-claim is respected (Section 9.2) and external de-activation stops tracker-driven
  dispatch (Section 9.3).
- The host exposes an issue-scoped run-stop capability to plugins, and external de-activation uses
  it when a tracker-driven run is active (Section 9.3).
- Per-issue execution uses host workspaces (Section 9.4).
- Workflow policy lookup is implemented for at least one source (Section 9.5).
- Claim/run/retry/release state is observable per link (Section 12).

## 10. Outbound Synchronization and Write Policy (Paperclip → External)

### 10.1 Write Boundary

All provider writes flow through the connector's Outbound Write Engine or connector-provided
agent tools. Host core logic MUST NOT write to providers. Agent tools that write externally are
connector tools with the same policy checks as engine writes. (This is Symphony's tracker-writes
boundary, kept.)

Every outbound write MUST be:

- Policy-checked against the link's `syncMode` and `fieldPolicy` and the write toggles below.
- Idempotent under the outbound idempotency key (Section 4.3).
- Attributed (Section 10.4) and audit-logged (Section 14.5).

### 10.2 Write Policy Toggles and Defaults

Per link (with connector-instance defaults):

| Toggle | Default | Meaning |
| --- | --- | --- |
| `postBacklink` | on | Paperclip URL on the external task (field or pinned comment). |
| `postProgressComments` | on | Concise milestone comments: claimed, plan ready, PR opened, review requested, done. |
| `postArtifactLinks` | on | PR/work-product/document links when produced. |
| `mirrorAgentComments` | off | Full Paperclip comment thread mirrored externally. |
| `postTranscripts` | off | Run logs/transcripts externally. SHOULD remain off; transcripts may contain sensitive context. |
| `projectStatus` | on | Status projection per Section 10.3. |
| `mirrorExternalComments` | on (import side) | External comments imported per Section 7.3. |

Progress comments MUST be concise and milestone-based, not per-heartbeat chatter. Connectors
SHOULD batch/debounce outbound comments (RECOMMENDED minimum interval 5 minutes per link except
for claim/done/review milestones).

### 10.3 Status Projection

Paperclip issue status projects to provider states through the same mapping table as Section 7.2,
inverted, with these rules:

- Projection only moves the external task between states the operator mapped; unmapped Paperclip
  statuses project as comments, not transitions.
- `in_review` projects to the mapped `review` state where one exists — the Symphony handoff
  pattern — otherwise stays in `active` with a review-requested comment.
- `done` projects to the mapped terminal state only when `fieldPolicy.state` permits
  Paperclip-side closure; otherwise it posts a completion comment and leaves the transition to
  external users.
- Claim/run state (claimed by which agent, running, retrying, released) SHOULD be projected into a
  custom field or status comment where the provider allows, so external users see liveness.

### 10.4 Attribution and Echo Suppression

- Outbound writes use the connector instance's service account. Message bodies MUST carry agent
  attribution and the Paperclip issue link.
- Inbound processing MUST drop events authored by the connector's own service account
  (`isConnectorServiceAccount`) **and** events matching a recently-issued outbound idempotency
  key, preventing echo loops with providers that obscure authorship.
- Mirrored content MUST be marked so a second connector instance never re-mirrors it (loop
  prevention across instances): a stable marker (hidden metadata or footer convention) is
  REQUIRED on all mirrored comments.

## 11. Conflict Detection and Resolution

### 11.1 Detection

Three-way comparison per synced field: `baseSnapshot` vs current external value vs current
Paperclip value.

- Changed on one side only → propagate per `fieldPolicy` (or queue conflict if the changed side
  is not the owner).
- Changed on both sides since base → conflict entry.
- Structural conflicts (Section 6.4 deletion, Section 7.4 terminal-while-active, routing failure)
  are first-class conflict kinds.

### 11.2 Conflict Entry

Fields: `linkId`, `kind` (`field`, `deletion`, `closure`, `routing`, `policy`), `field` (when
applicable), `baseValue`, `externalValue`, `paperclipValue`, `detectedAt`, `actors` (both sides
where known), `status` (`open`, `resolved`, `dismissed`), `resolution`.

### 11.3 Resolution Actions

Exposed in the conflict queue UI and as agent-invocable connector tools:

- `keep_paperclip` (push Paperclip value outbound)
- `keep_external` (apply external value inbound)
- `merge_manual` (operator/agent supplies the merged value)
- `unlink`
- `dismiss` (acknowledge without change; updates `baseSnapshot` to current values)

Resolving a conflict MUST update `baseSnapshot` so the same divergence is not re-detected. Open
conflicts MUST NOT block unrelated fields from syncing.

## 12. Observability and Health

### 12.1 Logging Conventions

Connector log entries MUST carry: `connectorInstanceId`, `providerKey`, `linkId` (when bound),
`externalTaskId`/`externalKey`, `issueId`/issue identifier, event kind, idempotency key, and
outcome. Plugin activity logging is the REQUIRED sink; additional sinks are
implementation-defined.

### 12.2 Health Surface (REQUIRED)

Per connector instance, operators MUST be able to see `ConnectorHealth` (Section 4.1.8) plus:

- cursor positions and lag estimates,
- inbound queue depth and oldest pending event age,
- scheduled retries with next-due times,
- open conflicts (count + queue link),
- last 50 sync errors with categories.

### 12.3 Link Surface (REQUIRED)

Per linked issue (issue-detail integration), users MUST be able to see: external key/title/URL and
current external state; sync and run mode; field ownership; the routing rule that selected the
assignee; last inbound/outbound/reconcile times; current claim/run/retry/release state; and
actions (open external, resync now, pause/resume, unlink, resolve conflict).

### 12.4 External-Side Surface (RECOMMENDED)

On the provider side, a linked task SHOULD show: the Paperclip backlink, current Paperclip
owner/status (field or comment), and concise progress per Section 10.2.

## 13. Failure Model and Recovery

### 13.1 Failure Classes

1. `Provider outage / transport failure` — retry with exponential backoff and jitter; health
   `degraded`; links untouched.
2. `Credential expiry` — health `error`, operator notification path REQUIRED; no link mutations.
3. `Webhook loss / delivery gaps` — repaired by polling backstop and reconciliation; this is why
   Section 7.1.3 is REQUIRED.
4. `Cursor loss/corruption` — bounded re-list with idempotent re-apply (Section 5.4).
5. `Rate limiting` — honor provider guidance; shed reconciliation load before shedding webhook
   processing; never drop queued inbound events on rate limits.
6. `Partial apply crash` — idempotency keys + transactional cursor persistence (Section 4.1.7)
   make re-apply safe.
7. `Poison event` — an event that repeatedly fails application is parked with a health entry after
   a bounded retry count (RECOMMENDED 5); it MUST NOT block the per-task queue forever.
8. `Provider schema drift` — unknown payload shapes degrade to `provider_payload` errors with the
   raw payload preserved for diagnosis; known-good fields continue to apply.

### 13.2 Restart Recovery

Connector restart recovery is cursor- and link-store-driven: re-verify webhook registration,
resume cursors, run one reconciliation pass. In-memory queue contents may be lost; reconciliation
repairs the gap. No durable orchestrator state beyond the link store and cursors is REQUIRED.

### 13.3 Operator Intervention Points

Operators MUST be able to: pause/resume a connector instance; pause/resume a single link; force
resync of a link; replay a parked event; rotate credentials; and unlink. All interventions are
audit-logged.

## 14. Security and Governance

### 14.1 Company Boundary

Every connector instance binds to exactly one company. Every inbound effect MUST resolve its
target company from the link/connector instance before any mutation, and MUST NOT cross
companies. Multi-company installations are separate connector instances with separate credentials
and state.

### 14.2 Credentials and Webhooks

- Provider tokens/OAuth grants MUST be stored as secret references, never inline configuration or
  plugin state.
- Webhook endpoints MUST verify provider signatures where offered; unverifiable webhook payloads
  are hints requiring API read-back (Section 5.1(5)).
- Webhook endpoints MUST reject payloads that do not match the connector instance's registered
  provider workspace.

### 14.3 Untrusted Content and Commands

- All external content (titles, descriptions, comments, field values, workflow files) is
  untrusted input with provenance, per Sections 7.3 and 9.5.1.
- Comment commands are parsed deterministically (Section 8.2); free-text external content MUST
  NOT trigger privileged actions.
- Workflow policy is lowest-precedence guidance (Section 9.5) — it cannot grant capabilities,
  alter governance, or override system instructions.

### 14.4 Governance Invariants

No connector path may bypass:

- issue checkout/claim exclusivity,
- budget hard-stops and pause/cancel,
- approval gates and execution-policy stages,
- blocker semantics,
- company boundaries.

External signals translate into host-level requests subject to all of the above (Section 7.4).
Destructive cascade is prohibited: external deletion/archival never deletes Paperclip work
(Section 6.4).

### 14.5 Audit

Every mutation on either side carries attribution: connector instance, link, triggering event
idempotency key, and acting identity (external actor inbound; agent + connector service account
outbound). Audit entries are queryable per link.

## 15. Reference Flows (Language-Agnostic)

### 15.1 Import One External Task

```
on import_request(externalTaskId):
  task = adapter.getTask(externalTaskId)
  if dedupe_hit(task): surface_existing_link(); stop
  company, project, goal = resolve_target(connector_instance)
  assignee = routing.resolve(task)            # Section 8; triage fallback guaranteed
  packet  = render_projection(task)           # normalized fields only
  issue   = host.create_issue(company, project, goal, assignee, packet,
                              source_attribution(task))
  link    = links.create(task, issue, originSide=external,
                         baseSnapshot=snapshot(task, issue))
  if policy.postBacklink: adapter.setBacklink(task.externalId, issue.url)
  health.record(inbound_ok)
```

### 15.2 Inbound Comment

```
on provider_comment_event(evt):
  evt = verify_or_readback(evt)
  if evt.actor.isConnectorServiceAccount or echo_match(evt): drop
  if not idempotency.first_time(evt): drop
  link = links.by_external(evt.externalTaskId) or stop
  if command = parse_strict_command(evt.body):    # Section 8.2
      execute_and_reply(command); record; stop
  host.post_issue_comment(link.issueId, attributed(evt))   # provenance, untrusted
  if link.policy.wakeOnExternalComment: host.wake_assignee(link.issueId)
```

### 15.3 Tracker-Driven Execution Cycle (Symphony Profile)

```
on external_state_change(task) where link.runMode == symphony_compatible:
  category = state_mapping(task.state)
  issue = host.issue(link.issueId)
  if category == active and issue.status in {done, cancelled}:
      if reopen_policy == follow_up:
          issue = host.create_or_get_follow_up(
              issue, inherit_workspace=true, idempotency_key=stable_key(task))
          link = links.retarget(link, issue)  # one entity upsert: new issueId + handoffHistory
      else:
          issue = host.request_resume(issue)                    # normal host resume rules
  if category == active and issue.status == backlog:
      issue = host.set_status(issue.id, todo)                   # backlog is not wakeable
  if category == active and issue_dispatchable(issue):
      host.wake_assignee(issue.id)                              # debounced
  if category in {backlog, blocked, terminal} and tracker_driven_run_active(link):
      if host.capabilities.issueScopedRunStop:
          host.request_issue_run_stop(link.issueId)
      else:
          health.record(issue_run_stop_unsupported)             # let this run finish
      if category == terminal and issue_active(link.issueId):
          conflicts.open(link, kind=closure)      # Section 7.4

on issue_status_change(issue) where linked(issue):
  outbound.project_status(link, issue.status)     # Section 10.3, policy-gated
  outbound.post_milestone_comment_if_due(link, issue)
```

### 15.4 Reconciliation Tick

```
every reconcile_interval per connector_instance:
  for link in links.window(cursor):               # rate-bounded slice
    state = adapter.getTaskStates([link.externalTaskId])
    if missing(state): conflicts.open(link, kind=deletion); continue
    diff = three_way(link.baseSnapshot, state, host.issue(link.issueId))
    apply_owned_changes(diff)                      # Section 11.1
    queue_conflicts(diff)
    link.lastReconcileAt = now
  health.record(reconcile_ok, cursor)
```

## 16. Conformance Checklist (Definition of Done)

### 16.1 REQUIRED for Core Conformance (Layers 1–2)

- Task Source Adapter with `listCandidateTasks`, `getTask`, `getTaskStates`, `listComments`,
  webhook verification or documented poll-only posture
- Static capability declaration consumed by host UX
- Normalized `ExternalTask` output with provider envelope separation
- Task link store with the Section 4.1.3 invariants and Section 6.1 state machine
- Idempotent inbound apply (event idempotency keys + transactional cursors)
- Deduplicated link creation (Section 6.3)
- External deletion handled non-destructively (Section 6.4)
- Explicit state-category mapping with unmapped-state safety (Section 7.2)
- Comment import with provenance and untrusted-content handling (Section 7.3)
- Routing pipeline with guaranteed triage fallback (Section 8)
- Reconciliation job (Section 7.1.3)
- Health and link surfaces (Sections 12.2, 12.3)
- Secret-ref credentials, company-boundary enforcement, audit attribution (Section 14)

### 16.2 REQUIRED for Symphony Profile Conformance (Layer 3)

- `runMode=symphony_compatible` honoring Section 9.1 dispatch (wake, never spawn)
- Checkout-as-claim with no parallel claim registry (Section 9.2)
- External de-activation stops tracker-driven dispatch and uses an issue-scoped host run-stop
  capability for an active issue run (Section 9.3)
- Debounced wake requests (Section 9.3)
- Task packet rendering with strict variables and untrusted marking (Section 9.5.1)
- Workflow policy lookup from at least one source with lowest-precedence guarantee (Section 9.5)
- Claim/run/retry/release state visible per link (Section 12.3)

### 16.3 REQUIRED for Write Conformance (Layer 4)

- Outbound writes only via Outbound Write Engine / connector tools (Section 10.1)
- Policy toggles with Section 10.2 defaults, including transcripts off
- Idempotent outbound effects
- Status projection rules including review-handoff and gated closure (Section 10.3)
- Service-account attribution, echo suppression, and cross-instance loop markers (Section 10.4)
- Three-way conflict detection with resolution actions and base-snapshot advance (Section 11)

### 16.4 RECOMMENDED Extensions (Not REQUIRED for Conformance)

- External-side claim/run state projection into provider custom fields
- `user_mapping` routing and "assign back to me" flows
- Lossless rich-text round-trip per provider
- Comment-command verb extensions (e.g. `/paperclip plan`, `/paperclip qa`)
- Promotion of task links from plugin state to core schema once two providers validate the model

## Appendix A. Provider Profiles

Each profile lists container coordinates, envelope content, state-mapping notes, and known write
constraints. Profiles are informative; the normative contract is Sections 4–14.

### A.1 Linear

- Containers: team, project, cycle. Envelope: issue key, workflow state id/type, labels with ids,
  branch name, relations, estimates, cycle/project ids.
- State mapping: Linear workflow state `type` (`backlog`, `unstarted`, `started`, `completed`,
  `canceled`) gives a reliable default category mapping; per-team overrides supported.
- Webhooks: signed; verification REQUIRED. API: GraphQL; pagination REQUIRED; keep queries
  isolated (schema drift).
- Notes: closest provider to the Symphony reference; RECOMMENDED first connector.

### A.2 Jira

- Containers: site/cloud id, project key. Envelope: issue type, workflow transition ids, status
  category, components, epic/parent links, sprints, custom fields by id.
- State mapping: map via Jira status categories (`To Do`, `In Progress`, `Done`) plus named-status
  overrides; transitions require transition ids, so `updateTaskState` resolves transitions at
  apply time.
- Webhooks: available (signed via secret on Cloud); polling backstop RECOMMENDED.
- Notes: per-project workflow variance is the main mapping risk; setup MUST validate against live
  workflow metadata.

### A.3 Asana

- Containers: workspace, project, section. Envelope: section memberships, custom fields,
  followers, multi-project memberships.
- State mapping: Asana has completion plus sections; map sections→categories per project;
  completion maps to `terminal`.
- Webhooks: handshake + HMAC signatures; verification REQUIRED.
- Notes: multi-project membership means one task can match several containers — the link binds to
  the connector instance's configured container.

### A.4 Notion

- Containers: database id. Envelope: property schema snapshot, select/status property values,
  relation properties, block-content references.
- State mapping: a designated status/select property maps to categories; databases without one
  are import/browse only (no Symphony profile).
- Webhooks: limited; polling with `last_edited_time` high-water mark is the primary channel.
- Notes: rich-text conversion is lossy; envelope SHOULD retain block references for backlinks.

### A.5 Trello

- Containers: board, list. Envelope: list id, checklists, members, power-up metadata, card
  position.
- State mapping: lists are lanes; map lists→categories (`Paperclip: QA` style lanes also drive
  `state_lane` routing).
- Webhooks: available with callback verification; signatures via content digest.
- Notes: no native blockers/priority; both normalize to null/empty with envelope passthrough.

### A.6 GitHub Issues

- Containers: repository (and optionally Projects v2). Envelope: labels, milestones, assignees,
  linked PR references, reactions.
- State mapping: open/closed plus label conventions or Projects v2 status field for richer
  categories.
- Webhooks: HMAC-signed; verification REQUIRED.
- Notes: PR linkage is first-class here; `postArtifactLinks` SHOULD use native cross-references.

## Appendix B. Symphony Spec Crosswalk

| Symphony SPEC.md section | This document |
| --- | --- |
| 1 Problem Statement | 1 |
| 2 Goals / Non-Goals | 2 |
| 3 System Overview | 3 |
| 4 Core Domain Model (Issue, Run Attempt, Retry Entry, Runtime State) | 4 (`ExternalTask`, `TaskLink`, host run state via 9.3) |
| 5 Workflow Specification (`WORKFLOW.md`) | 9.5 (layered workflow policy) |
| 6 Configuration Specification | connector instance configuration (3.4, 5.2, 7.2, 10.2) |
| 7 Orchestration State Machine | 6.1 (link), 9.3 (claim/run/retry/release on host primitives) |
| 8 Polling, Scheduling, Reconciliation | 7.1, 9.1, 15.4 |
| 9 Workspace Management and Safety | 9.4 (host execution workspaces) |
| 10 Agent Runner Protocol | host heartbeat runtime (out of scope here; see 9.1 boundary) |
| 11 Issue Tracker Integration Contract | 5 (Task Source Adapter contract) |
| 11.5 Tracker Writes boundary | 10.1 |
| 12 Prompt Construction | 9.5.1 (task packet rendering) |
| 13 Logging, Status, Observability | 12 |
| 14 Failure Model and Recovery | 13 |
| 15 Security and Operational Safety | 14 |
| 16 Reference Algorithms | 15 |
| 17–18 Test Matrix / Implementation Checklist | 16 |
| Appendix A SSH Worker | not applicable (host owns execution substrate) |

Differences are deliberate: Symphony assumes one tracker, one repo, and coding agents only, with
the orchestrator as a standalone daemon. This protocol assumes a multi-tenant control plane that
already owns claims, runs, workspaces, and governance — so the connector's scope shrinks to
normalization, linking, routing, sync policy, and observability, and Symphony's
orchestrator/runner sections collapse onto existing host primitives.