# Forgejo Issue Sync Plugin

Paperclip plugin for one-way Paperclip issue -> Forgejo issue creation while enforcing the v1 attachment policy:

- selected Paperclip issues are detected inside the plugin worker
- scheduled reconciliation stays in plugin `jobs`
- mappings, dedupe, and review state stay in the plugin database/state
- attachment handling is metadata-only
- no managed agents or managed skills are declared in v1

## Layout

- `src/manifest.ts`: manifest, capabilities, jobs, webhook declaration, instance config schema
- `src/worker.ts`: plugin bootstrap, health, config validation, data/action registration
- `src/paperclip-issue-sync.ts`: issue selection, payload shaping, and outbound sync flow
- `src/forgejo-client.ts`: outbound Forgejo API client
- `src/reconciliation.ts`: scheduled reconciliation job and instance-level last-run state
- `src/persistence.ts`: namespace-local persistence helpers for mappings, reviews, and run snapshots
- `src/attachment-policy.ts`: metadata-only attachment policy and synced markdown formatter
- `migrations/001_initial.sql`: plugin-owned tables for mappings, dedupe, review queue, and reconciliation history

## Attachment Policy

This plugin deliberately does not fetch attachment bytes and does not add any path that calls `/api/attachments/{id}/content`.

Instead it:

- preserves attachment metadata only
- appends `Attachments are not synced. See the source Paperclip issue.` to generated sync content
- stores a machine-readable review reason code when the issue/comment text suggests the attachment is required for context
- queues those payloads in `review_queue` for later human-routing work

## Follow-Up Needed

The plugin emits `attachments_context_required` as a durable review signal, but the human-review destination is still a follow-up decision:

- create Paperclip-visible review issues/comments
- expose a plugin UI or scoped API route for triage
- route review-required payloads into an existing operator workflow

That routing is intentionally left out of this v1 scaffold so the sync runtime stays inside plugin jobs/webhooks/state as requested.