fusion/docs/agent-paperclip-gap-analysis.md

# Agent Paperclip-Style Gap Analysis

## Executive Summary
Fusion already has the core *shape* of a heartbeat-driven agent runtime: agents have lifecycle state, heartbeat runs are tracked, heartbeats can be triggered by timer/assignment/on-demand events, and agents can create follow-up tasks. This gives Fusion a strong baseline for the Paperclip execution model, especially around short-lived run execution (`HeartbeatMonitor.executeHeartbeat()`), agent persistence (`AgentStore`), and lightweight communication (`MessageStore`, task comments).

The largest gaps are ownership and coordination semantics. Paperclip’s model depends on explicit checkout leasing, inbox-driven work picking, blocked-task dedup, wake-context handling (including mention-triggered behavior), and budget-aware escalation rules. Fusion currently executes assigned work, but it does not enforce checkout-first locking or the comment/inbox contract that makes Paperclip runs predictable and conflict-safe.

Recommended priority: first add ownership/inbox primitives (checkout + inbox-lite + wake context), then add policy layers (blocked dedup, self-assignment constraints, communication conventions), and finally add advanced governance parity (budget controls, richer approval/doc workflows). Several adjacent foundations are already covered by existing Fusion tasks (assignment, hierarchy, permissions), so new work should build on those rather than duplicate them.

## Pattern Inventory

### Implemented Patterns

| Pattern | Fusion Implementation | Location in Code |
|---|---|---|
| Heartbeat run execution loop | Wake → task resolution → agent session → run completion | `packages/engine/src/agent-heartbeat.ts` |
| Heartbeat trigger mechanisms | Timer, assignment, and on-demand trigger scheduling | `packages/engine/src/agent-heartbeat.ts` (`HeartbeatTriggerScheduler`), `packages/dashboard/src/routes.ts` (`POST /agents/:id/runs`) |
| Attachment CRUD | Upload/list/download/delete task attachments | `packages/dashboard/src/routes.ts` (`/tasks/:id/attachments*`), `packages/core/src/store.ts` |

### Partial Implementations

| Pattern | What Exists | What's Missing | Packages Affected | Complexity |
|---|---|---|---|---|
| Heartbeat Procedure (9-step) | Simplified wake→check assignment→work→exit | No approval-follow-up, inbox prioritization, checkout, blocked dedup, delegation semantics parity | engine, core, dashboard | M |
| Wake context variables | `contextSnapshot`, `source`, `triggerDetail`, optional `taskId` | No `PAPERCLIP_WAKE_COMMENT_ID`, approval context vars, or env-style propagation | engine, dashboard, core | M |
| Communication model | Task comments + `MessageStore` mailboxes | No mention-routing semantics, no required ticket-link markdown rules | core, dashboard, engine | M |
| Delegation model | `spawn_agent` + `task_create` + dependencies | No `parentId`/`goalId` issue graph semantics, no workspace inheritance flags | core, engine, dashboard | M |
| Chain of command | `reportsTo` hierarchy and `/agents/:id/children` | No explicit `chainOfCommand` resolution/escalation policy in heartbeat flow | core, engine, dashboard | M |
| Routines | Automation schedules and manual runs exist | Not agent-inbox-native routines with webhook/api triggers + catch-up/concurrency policies | core, engine, dashboard | L |
| Planning mode docs | Planning sessions and summary-based task creation | No issue document key/revision API parity (`plan` doc revisions) | core, dashboard, engine | M |
| Approval workflow | `requirePlanApproval`, approve/reject-plan routes | No approval entity model with linked issues and resolution-first heartbeat handling | core, engine, dashboard | M |
| Status model parity | Fusion columns + task status fields | Missing direct parity with `backlog/in_progress/blocked/cancelled` lifecycle model | core, dashboard, engine | M |
| Error-handling policy | Run failure/termination handling and state transitions | No hard rule enforcement (checkout-first, mandatory end-comment, no cross-team cancel) | engine, core | M |
| Agent identity endpoint | `/agents/:id` and run stats exist | No `/agents/me` contract with company-scoped identity + budget fields | dashboard, core | S |
| Instructions-path API parity | `/agents/:id/instructions` supports path/text updates | No dedicated `/agents/:id/instructions-path` endpoint semantics | dashboard, core | S |

### Missing Patterns

| Pattern | Description | Packages Affected | Complexity | Dependencies |
|---|---|---|---|---|
| Checkout mechanism | Exclusive checkout API with 409 conflict semantics and no-retry policy | core, dashboard, engine | L | Task-agent assignment foundation (FN-1096/1098/1099) |
| Inbox-lite work selection | Compact assignment inbox with `in_progress` then `todo` priority and blocked handling | core, dashboard, engine | M | Checkout mechanism |
| Blocked-task dedup | Skip redundant blocked comments when no new context | core, engine | M | Inbox/comment cursor support |
| Budget management | Per-agent budget tracking, 80% throttling, 100% auto-pause | core, engine, dashboard | L | Agent metrics foundations (FN-1184 family) |
| Self-assignment mention handoff rules | Restrict self-assignment to explicit mention-triggered ownership transfer | engine, dashboard, core | M | Inbox + mention wake context |
| Issue search parity | Full-text search across title/identifier/description/comments | core, dashboard | M | Unified indexing strategy |
| Run audit trail header semantics | Uniform mutating-action run correlation equivalent to `X-Paperclip-Run-Id` policy | engine, dashboard, core | M | Checkout + identity context |
| Comment link policy enforcement | Auto-link ticket IDs and enforce company-prefixed internal URL style | dashboard, engine | S | Issue identifier conventions |
| Send-back-to-user handoff | Support assigning tasks back to user (`assigneeUserId`) with `in_review` handoff pattern | core, dashboard, engine | M | Expanded assignee model |

### Not Applicable

| Pattern | Reason it doesn't apply |
|---|---|
| Commit co-author rule (`Co-Authored-By: Paperclip`) | Paperclip-specific governance requirement; Fusion uses task-scoped commit conventions (`feat(FN-xxx): ...`) |
| OpenClaw invite workflow | Paperclip/OpenClaw org provisioning concern, not a Fusion board runtime concern |
| Paperclip company skills workflow APIs | Fusion has no company-level skill package registry model matching Paperclip |
| Paperclip project/workspace setup API shape | Fusion project registration exists but not via Paperclip issue-workflow endpoints |
| Full Paperclip control-plane API parity | Fusion is a different product surface; only overlapping agent-runtime patterns are relevant |

## Detailed Analysis

### 1) Heartbeat Procedure (9-step)
**Status:** PARTIAL  
**Description:** Paperclip requires identity/approval/inbox/pick/checkout/context/work/status/delegate every wake.  
**Current State:** Fusion executes a compact heartbeat run (`executeHeartbeat`) with task fetch and tool-enabled session.  
**Gap:** Missing approval-first branch, inbox-lite prioritization, explicit checkout, and blocked dedup policy.  
**Recommendation:** Extend `executeHeartbeat()` into explicit policy stages and persist per-stage telemetry in run metadata.  
**Files Affected:** `packages/engine/src/agent-heartbeat.ts`, `packages/core/src/types.ts`

### 2) Checkout mechanism (409 no-retry)
**Status:** MISSING  
**Description:** Must claim ownership before work; 409 means abandon and pick different work.  
**Current State:** Fusion relies on scheduler movement/assignment; no explicit lease endpoint.  
**Gap:** No first-class lock/lease primitive with conflict semantics.  
**Recommendation:** Add checkout/release APIs and enforce checkout-before-work in heartbeat + executor flows.  
**Files Affected:** `packages/core/src/agent-store.ts`, `packages/core/src/store.ts`, `packages/dashboard/src/routes.ts`, `packages/engine/src/agent-heartbeat.ts`

### 3) Inbox-lite work selection
**Status:** MISSING  
**Description:** Compact assignment view with priority ordering and blocked filtering.  
**Current State:** Heartbeat resolves a single assigned task (`agent.taskId`).  
**Gap:** No ranked inbox endpoint or work-selection strategy.  
**Recommendation:** Introduce `/agents/:id/inbox-lite` equivalent and priority resolver in heartbeat scheduler.  
**Files Affected:** `packages/core/src/agent-store.ts`, `packages/dashboard/src/routes.ts`, `packages/engine/src/agent-heartbeat.ts`, `packages/engine/src/scheduler.ts`

### 4) Blocked-task dedup
**Status:** MISSING  
**Description:** Avoid repeated blocked updates unless new context appears.  
**Current State:** No built-in dedup against last blocked comment + comment cursor.  
**Gap:** Repetitive blocked churn is possible.  
**Recommendation:** Store last-blocked-comment metadata per task/agent and gate repeated updates.  
**Files Affected:** `packages/core/src/store.ts`, `packages/engine/src/agent-heartbeat.ts`

### 5) Wake context (`PAPERCLIP_*` parity)
**Status:** PARTIAL  
**Description:** Runs carry trigger reason, task/comment/approval context.  
**Current State:** `contextSnapshot` includes wake reason/trigger detail/taskId in run APIs.  
**Gap:** No structured comment-trigger and approval-resolution context model.  
**Recommendation:** Formalize wake context schema in `AgentHeartbeatRun.contextSnapshot` and propagate to prompts/tools.  
**Files Affected:** `packages/core/src/types.ts`, `packages/engine/src/agent-heartbeat.ts`, `packages/dashboard/src/routes.ts`

### 6) Communication model (comments, mentions, link style)
**Status:** PARTIAL  
**Description:** Paperclip uses issue comments, mention-driven wakes, and strict ticket-link markdown conventions.  
**Current State:** Fusion has task comments and message inbox/outbox APIs.  
**Gap:** No mention-to-wake semantics in task comments; no enforced link formatting conventions.  
**Recommendation:** Add mention parser and optional markdown linting for task comment references.  
**Files Affected:** `packages/core/src/message-store.ts`, `packages/core/src/store.ts`, `packages/dashboard/src/routes.ts`, `packages/engine/src/agent-heartbeat.ts`

### 7) Delegation model (`parentId`, `goalId`, workspace inheritance)
**Status:** PARTIAL  
**Description:** Delegation creates structured child/follow-up issues preserving goal/workspace lineage.  
**Current State:** Fusion supports `spawn_agent` and `task_create` with dependencies.  
**Gap:** No explicit parent/goal fields or non-child workspace inheritance marker.  
**Recommendation:** Extend task schema with optional parent/goal/workspace-link fields and expose in creation APIs.  
**Files Affected:** `packages/core/src/types.ts`, `packages/core/src/store.ts`, `packages/engine/src/agent-tools.ts`, `packages/dashboard/src/routes.ts`

### 8) Chain of command escalation
**Status:** PARTIAL  
**Description:** Escalation follows explicit `chainOfCommand`.  
**Current State:** `reportsTo` relationship exists with child lookup route.  
**Gap:** No computed chain traversal/escalation helper in runtime policies.  
**Recommendation:** Add `resolveChainOfCommand(agentId)` utility and escalation tool usage pattern in heartbeat instructions.  
**Files Affected:** `packages/core/src/agent-store.ts`, `packages/engine/src/agent-heartbeat.ts`, `packages/dashboard/src/routes.ts`

### 9) Budget management
**Status:** MISSING  
**Description:** Budget controls (80% focus narrowing, 100% auto-pause).  
**Current State:** Token usage totals are tracked, but no budget thresholds/policies exist.  
**Gap:** No budget envelope or policy enforcement.  
**Recommendation:** Add budget config to agent schema and gate trigger scheduler/execution when budget thresholds are crossed.  
**Files Affected:** `packages/core/src/types.ts`, `packages/core/src/agent-store.ts`, `packages/engine/src/agent-heartbeat.ts`, `packages/dashboard/src/routes.ts`

### 10) Routines
**Status:** PARTIAL  
**Description:** Recurring task triggers integrated with agent inbox pickup and routine policies.  
**Current State:** Fusion automations support cron-like scheduling and manual runs.  
**Gap:** No routine-to-agent-assignment model with dedicated catch-up/concurrency policy vocabulary.  
**Recommendation:** Either map routines onto automation primitives with explicit policy fields or add dedicated routine entities.  
**Files Affected:** `packages/core` (automation domain), `packages/engine` (trigger integration), `packages/dashboard/src/routes.ts`

### 11) Planning mode document revisions
**Status:** PARTIAL  
**Description:** Plan documents keyed by identifier with revision history.  
**Current State:** Planning sessions and summaries exist; task prompt persists spec text.  
**Gap:** No key-based issue document API with base-revision concurrency control.  
**Recommendation:** Add per-task document store (`plan`, etc.) and revision endpoints.  
**Files Affected:** `packages/core/src/store.ts`, `packages/core/src/types.ts`, `packages/dashboard/src/routes.ts`

### 12) Approval workflows
**Status:** PARTIAL  
**Description:** Approval entities linked to issues, reviewed first on wake.  
**Current State:** Planned tasks can require manual approval (`awaiting-approval` + approve/reject routes).  
**Gap:** No standalone approval objects with linked issue resolution metadata.  
**Recommendation:** Add optional approval domain only if needed beyond existing planning approval.  
**Files Affected:** `packages/engine/src/planning.ts`, `packages/dashboard/src/routes.ts`, `packages/core/src/types.ts`

### 13) Self-assignment constraints
**Status:** MISSING  
**Description:** Self-assignment allowed only for explicit mention handoff context.  
**Current State:** Explicit task assignment exists (`PATCH /tasks/:id/assign`) without mention-gated policy.  
**Gap:** Ownership can be changed without mention-driven context checks.  
**Recommendation:** Add policy checks in assignment route/runtime for mention-handoff mode when agent-initiated.  
**Files Affected:** `packages/dashboard/src/routes.ts`, `packages/core/src/store.ts`, `packages/engine/src/agent-heartbeat.ts`

### 14) Status value parity
**Status:** PARTIAL  
**Description:** Paperclip issue statuses differ from Fusion’s board columns/status fields.  
**Current State:** Fusion has columns (`planning`, `todo`, `in-progress`, `in-review`, `done`, `archived`) and ad-hoc task status strings.  
**Gap:** No direct `blocked/cancelled/backlog` canonical lifecycle.  
**Recommendation:** Decide whether to add a normalized execution status enum alongside board columns.  
**Files Affected:** `packages/core/src/types.ts`, `packages/core/src/store.ts`, `packages/dashboard/src/routes.ts`, `packages/engine/src/scheduler.ts`

### 15) Error-handling policy rules
**Status:** PARTIAL  
**Description:** Paperclip enforces checkout-first, mandatory heartbeat comments, and cross-team cancellation restrictions.  
**Current State:** Fusion tracks run failures and transitions states robustly.  
**Gap:** Governance rules are not codified as hard guards.  
**Recommendation:** Add policy middleware in heartbeat execution and task mutation routes.  
**Files Affected:** `packages/engine/src/agent-heartbeat.ts`, `packages/dashboard/src/routes.ts`, `packages/core/src/store.ts`

### 16) Issue search across comments
**Status:** MISSING  
**Description:** Full-text search over title/identifier/description/comments.  
**Current State:** Task list endpoint supports pagination; no query search parameter.  
**Gap:** No index-backed search route covering comments.  
**Recommendation:** Add SQLite FTS index (or equivalent) for task/comment fields and `q=` API.  
**Files Affected:** `packages/core/src/store.ts`, `packages/dashboard/src/routes.ts`

### 17) Attachments API
**Status:** IMPLEMENTED  
**Description:** Upload/list/get/delete artifact attachments per work item.  
**Current State:** Fusion supports attachment upload, retrieval, listing, and deletion for tasks.  
**Gap:** Endpoint shape differs from Paperclip, but core capability exists.  
**Recommendation:** Keep as-is unless external API parity is required.  
**Files Affected:** `packages/dashboard/src/routes.ts`, `packages/core/src/store.ts`

### 18) Agent identity (`GET /me`, role, budget)
**Status:** PARTIAL  
**Description:** Single identity endpoint returns effective role, company scope, budget, chain-of-command metadata.  
**Current State:** Fusion provides `GET /agents/:id` and list endpoints; role/state metadata exists.  
**Gap:** No canonical `/agents/me` and no company/budget identity payload.  
**Recommendation:** Add authenticated `/agents/me` route and extend identity model if budget features are adopted.  
**Files Affected:** `packages/dashboard/src/routes.ts`, `packages/core/src/types.ts`

### 19) Run audit trail mutation header parity
**Status:** MISSING  
**Description:** Every mutating action should be tied to current run identity for auditability.  
**Current State:** Run IDs are persisted for heartbeats, but mutation APIs do not require run-scoped correlation headers.  
**Gap:** Hard to trace all side effects to one heartbeat transaction.  
**Recommendation:** Add optional/required run-correlation metadata for agent-initiated mutations.  
**Files Affected:** `packages/dashboard/src/routes.ts`, `packages/core/src/store.ts`, `packages/engine/src/agent-heartbeat.ts`

### 20) Commit co-author governance
**Status:** NOT APPLICABLE  
**Description:** Paperclip requires a specific co-author line in git commits.  
**Current State:** Fusion enforces task ID commit conventions.  
**Gap:** Governance mismatch is intentional.  
**Recommendation:** No action unless product policy changes.  
**Files Affected:** None

### 21) Company-prefixed ticket-link conventions
**Status:** MISSING  
**Description:** All ticket references should be markdown links with company prefix paths.  
**Current State:** No automatic formatting/linting of task comment references.  
**Gap:** Linking behavior is user-dependent and inconsistent.  
**Recommendation:** Add optional comment formatter/linter for task/agent outputs.  
**Files Affected:** `packages/dashboard/src/routes.ts`, `packages/engine/src/agent-heartbeat.ts`

### 22) OpenClaw invite workflow
**Status:** NOT APPLICABLE  
**Description:** CEO-only OpenClaw invite prompt generation and approval.  
**Current State:** Not part of Fusion’s domain model.  
**Gap:** Out of product scope.  
**Recommendation:** None.  
**Files Affected:** None

### 23) Company skills workflow parity
**Status:** NOT APPLICABLE  
**Description:** Company skill import/scan/sync APIs.  
**Current State:** Fusion has local skill references/instructions, not Paperclip company skill registry APIs.  
**Gap:** Different product boundaries.  
**Recommendation:** None (unless Fusion adopts company-level skill governance).  
**Files Affected:** None

### 24) Instructions-path dedicated endpoint parity
**Status:** PARTIAL  
**Description:** Dedicated endpoint to update only instruction file path.  
**Current State:** Fusion supports generic instruction updates on `/agents/:id/instructions` and full patch route.  
**Gap:** No endpoint-level parity with adapter-key semantics.  
**Recommendation:** Add alias route only if external parity/testing needs it.  
**Files Affected:** `packages/dashboard/src/routes.ts`

### 25) Send-back-to-user handoff
**Status:** MISSING  
**Description:** Explicit handoff from agent back to requesting user (`in_review`, assigneeUserId).  
**Current State:** Task assignment supports `assignedAgentId` only.  
**Gap:** No user assignee field or handoff policy.  
**Recommendation:** Add user-assignment fields and route support for review handoff workflows.  
**Files Affected:** `packages/core/src/types.ts`, `packages/core/src/store.ts`, `packages/dashboard/src/routes.ts`, `packages/engine/src/agent-heartbeat.ts`

## Recommended Implementation Order

1. **Ownership foundation:** implement checkout/release semantics and conflict handling (409 no-retry rule).  
2. **Work selection foundation:** add inbox-lite endpoint + deterministic prioritization + wake-context schema upgrades.  
3. **Policy layer:** blocked-task dedup, self-assignment mention guardrails, and run-audit correlation metadata.  
4. **Communication layer:** mention-triggered wake routing and ticket-link formatting helpers.  
5. **Escalation and governance:** chain-of-command runtime helpers + budget thresholds/auto-pause behavior.  
6. **Workflow parity upgrades:** planning document revisions + richer approval entities (if needed beyond current `awaiting-approval`).  
7. **Search and UX parity:** full-text issue/task search and optional `/agents/me` identity endpoint.  
8. **Deferred/optional parity:** instructions-path alias route and any Paperclip-specific API-shape harmonization.

## Existing Related Tasks

- **FN-1085 (end-to-end agent review):** General agent behavior consistency and bug fixes; relevant umbrella but not a direct replacement for checkout/inbox/budget features.
- **FN-1096 / FN-1098 / FN-1099 (task-agent assignment):** Foundational for checkout/inbox ownership semantics. New work should depend on these conventions rather than redefine assignment.
- **FN-1119 (agent API keys):** Covers auth substrate useful for any future `/agents/me` and run-audit identity policies.
- **FN-1122 (agent permissions):** Relevant for self-assignment restrictions, checkout authorization, and escalation actions.
- **FN-1164 / FN-1165 / FN-1167 (org chart / chain of command):** Direct overlap with escalation-chain gap; avoid duplicate hierarchy modeling.
- **FN-1170 / FN-1172 / FN-1173 (agent instructions):** Overlaps with instructions-path parity and prompt-policy rollout.
- **FN-1181 / FN-1182 / FN-1183 (agent self-reflection):** Can complement blocked dedup and policy-aware heartbeat decisions.
- **FN-1184 / FN-1185 / FN-1186 / FN-1187 (agent performance ratings):** Useful dependency/input for budget-governance and execution throttling logic.