The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
docs: add External Task Protocol specification (#10568)
Dotta2cbbad16fd4e
diff --git a/docs/specs/external-task-protocol.md b/docs/specs/external-task-protocol.mdnew file mode 100644index 0000000000..78bdf7d1d2--- /dev/null+++ b/docs/specs/external-task-protocol.md@@ -0,0 +1,1197 @@+# 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. Links and+follow-up issues that must share a checkout use host workspace-inheritance+(`inheritExecutionWorkspaceFromIssueId`); 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.