Paperclip Linear Intake

A separate Paperclip plugin that retains an authorized Linear transition to Todo, reads and imports its selected source family, and supplies current source attestations to an explicitly enabled Council receiver. Council owns admission, accounting and implementation dispatch.

Event/action continuity candidate (source 0.6.6): signed relevant Issue changes for enrolled fixed campaigns are retained before webhook acknowledgement, then coalesced into a native invalidation document. Council requests complete source observations only for a retained event or an actual action/publication. Idle and paused ticks perform no freshness source scans. Explicit resume checks the complete source; uncertain publications use bounded targeted readback under their original intent. Completed challenges replay their durable response without remote reads. See the technical contract. These are source and isolated test results; this lot does not install, activate, resume or prove behavior on the recipe instance or a real Linear campaign.

Idle observation reduction (source 0.6.5): a Council request with no publications now makes one complete double source observation, after reconciling any previously claimed effects. The four-ticket fixture drops from 48 to 24 source calls per request. Publication checks and freshness remain unchanged; Council owns request cadence. See the qualification. This source change does not update or resume the recipe instance.

Source-read reduction candidate (source 0.6.3): publication keeps native checks before its durable claim and a complete source observation before send. The isolated qualification measures 24 fewer source calls per new ordinary effect. This is source and fixture evidence, not installation, activation or a successful live campaign.

Bounded correction candidate (source 0.6.2): see the follow-up ledger for engagement, publication-proof, diagnostic and final-summary corrections. Early individual stop before a fixed Council mission and recovery of the same campaign after a failed integration are explicitly deferred in the PRD/TAD. This source change does not install, configure or activate either plugin.

Fixed campaign publisher (qualified candidate 0.6.1): optional authenticated Council continuity now has a durable comment/status journal, exact readback and restart reconciliation. It remains disabled by default. Synthetic SDK and isolated PostgreSQL checks are complemented by the complete installed isolated campaign: two serial integrations, global review, terminal permission/readback and repository release. Linear/GitHub/model responses and usage remain fixtures; real Linear publication and recette activation are not qualified. See campaign publication and the PRD/TAD correction ledger.

Historical Lot 1 qualification: Lot 1 is qualified against SDK 2026.1005.0. The disabled plugin has read two enrolled leaves and one complete native Content Assistant family: parent plus three children, full descriptions, two internal blocking edges, eight unresolved external blocker references, and repeated paginated inventories. See the criterion ledger and proof.

At the Lot 1 checkpoint, version 0.1.4 from candidate 6747347 was installed in recipe. Its eleven runtime files match the exact-candidate CI build. Temporary source probe/reader enrollment was removed, the original disabled configuration restored, and the managed connection verified healthy. No webhook, import or Council admission is active. Lot 2 is complete in source version 0.2.0: 383 package/worker tests, 79 isolated PostgreSQL tests, independent review, Fallow and four CI checks pass. It adds request retention and a scheduled source reader, and was not installed in recipe by that lot. Lot 3 is complete in source version 0.3.0: 594 tests, independent review, the Fallow gate and four CI checks pass. Native families and uncertainty recovery are qualified with real core services and an isolated database. See the import criterion ledger. Lot 4 is complete within isolated qualification: intake 0.4.0 (00c3141) and Council 0.7.18 (1b5269c) demonstrate the installed handoff through settled N1 ready_for_review, before N2, on unchanged host 61b3fd57. Native workers, jobs, events, admission and accounting are real; Linear HTTP and CLI model content/usage are deterministic fixtures. Neither release is installed or activated in recipe by this lot. Historical receipts remain unchanged. See the Lot 4 ledger and limits, public receipt and handoff contract.

V1 L2 is implemented in source version 0.5.0. Behind a separate disabled enrollment, one exact paperclip-campaign marker selects an exact milestone, fully paginates enrolled project metadata, reads the selected descendants and imports at most 33 nodes under the campaign ticket. Source parent IDs remain unchanged while an explicit native mapping groups milestone roots under that ticket. Campaign readiness binds verified PRD/TAD bytes, a material source digest and a separate compatible-state observation. Fixture and isolated PostgreSQL qualification are documented in the V1 L2 ledger. The real gateway milestone response shape remains unqualified, so campaign activation remains blocked; no Linear write or provider run is part of this lot.

Lot 2 uses a signed raw-body webhook, an append-only delivery journal and stable company/organization/issue identities. It acknowledges valid transitions after persistence. The scheduled native job performs the initial source retrieval after the webhook; Lot 4 separately revalidates current source in response to Council challenges. Explicitly enabled operator actions retain their own bounded read scope. See retention semantics and qualification.

Local verification

Requires Node 24.20.0 and npm 11.19.0 (CI pins both).

npm ci --ignore-scripts --no-audit --no-fund
npm run check
npm run test:package

npm run check typechecks, builds and runs the SDK harness and actual worker RPC tests with synthetic host services. Dependencies come from the public npm registry and the committed lockfile; no adjacent checkout is needed. npm run test:package validates the controlled archive, installs the resulting .tgz in a temporary production-only consumer with lifecycle scripts disabled, and starts the packaged manifest and worker through their real SDK JSON-RPC path. See the npm release runbook for trusted-publisher setup, exact-version installation, compatibility and database-safe rollback.

The separate npm run test:postgres check requires an isolated PostgreSQL 18.1 database via INTAKE_TEST_DATABASE_URL, with database and user both intake_test. It recreates only the plugin schema in that disposable database. Never point this test at recipe. CI provisions its own PostgreSQL service and runs storage and worker integration tests, including concurrent deliveries and interrupted writes, in addition to the ordinary package tests.

The independent Fallow CI job uses the locked [email protected] and compares a pull request with its base SHA and a push with its preceding SHA. New branches and manual runs use the merge-base with the default branch (or the preceding commit when already at that base). Missing comparison history fails the check. The CI gate keeps introduced moderate CRAP findings with estimated zero coverage as warnings, matching the local static-audit policy for these findings. Actual measured coverage is not inferred from that estimate. Introduced high/critical complexity, imports, dependencies, cycles, boundaries and other native failures still block. Only this known moderate CRAP case can override a native failure; incomplete or unknown reports, attribution changes and tool errors fail closed. No analysis threshold or source suppression is changed. The exception also requires empty dead-code finding lists and zero dead-code counts/errors, including inherited debt. The fallow-audit artifact preserves the unchanged native JSON report and exit code, the derived gate.json, candidate/base SHAs, tool version and input hashes even when the audit fails. Only that audit directory is uploaded; local qualification evidence stays outside the upload.

To reproduce after npm run build:

audit_base=$(git rev-parse origin/main)
mkdir -p artifacts/fallow-local
audit_exit=0
npm run audit:static -- --base "$audit_base" --output-file artifacts/fallow-local/audit.json || audit_exit=$?
node scripts/fallow-ci-gate.mjs artifacts/fallow-local/audit.json "$audit_exit" "$audit_base" "$(git rev-parse HEAD)"

The audit disables telemetry and incremental caching. .fallowrc.json declares the Paperclip runtime and manual qualification entry points and excludes local artifacts/ copies; it does not relax analysis thresholds. Complexity reports use estimated coverage unless an actual coverage report is supplied. They are static evidence, separate from the synthetic tests and native qualification.

The installed 0.1.4 bytes match the CI artifact for 6747347. The authorized native REST campaign completed 28 source calls with no failed call. Historical 0.1.2/0.1.3 receipts remain separate from this qualification.

Configuration defaults to disabled retention, disabled native import, disabled Council handoff and disabled gateway discovery. Enabling retention requires scoped source settings, a webhook secret reference and explicit operator enrollment. Native import additionally requires nativeImportEnabled: true in the enrolled configuration. An explicitly enabled inspect-gateway action can inspect a configured named gateway catalog using a native secret reference. The separate probe-source action can make only its configured, bounded Linear reads for an authenticated operator; neither action imports issues or wakes agents. Startup, health and config validation perform no HTTP or secret reads.

The read-source-family action reads only an enrolled root's subtree, preserves historical descendants and external blockers, checks all pagination, then repeats details and inventories to reject observed changes. It returns source evidence with eligibility flags; it does not grant admission. This action also starts disabled and uses the same native secret reference and managed gateway.

Milestone mode additionally requires an enrolled campaignSource project scan, an exact catalog/adapter qualification record, exact reference contents and an explicit list of compatible state IDs. Omission keeps the historical Todo path. The read-campaign-source operator action and retained importer never write to Linear, alter source descriptions or relations, or wake an implementation agent.

gatewayTransport defaults to host_http, using the native ctx.http HTTPS path. Explicit local_loopback mode uses a direct Node HTTP connection to the exact configured http://127.0.0.1:<port>/mcp/gateways/<id> endpoint. It preserves the managed Linear connection and native secret resolution. No redirects, proxy environment variables, remote hosts or automatic transport fallback are allowed. See local transport setup and qualification for configuration, limits and the remaining native qualification steps.

Version 0.1.4 adds an explicit gatewayToolCallMode: "native_rest" option. Initialization and catalog discovery still authenticate the configured named MCP gateway. Tool calls then use only /api/tool-gateway/tools/call on that same origin, with the same dedicated credential in the native gateway header. The default call mode remains mcp; failures never switch modes automatically. nativeToolTimeoutMs defaults to 20,000 in REST mode and is bounded to 1,000–30,000 ms. The local client adds a 2,000 ms response allowance for those calls; the existing 10,000 ms local MCP limit is unchanged. No new capability, credential or host modification is needed. The native parent-family campaign qualified this option at 30,000 ms; cleanup restored the original MCP configuration.

Flow and remaining work

flowchart LR
    L[Linear: ticket enters Todo] --> W[Native Paperclip plugin webhook]
    W --> J[Durable request and native job]
    J --> M[Managed Linear MCP connection]
    M --> T[Native tasks, documents and dependencies]
    T --> C[Council admission and implementation]

The integration owns event verification, complete source retrieval, import identity, recovery, and the handoff. Council owns the project mandate, budget, execution order, review, and acceptance.

The webhook, durable request and source-reading job are implemented in 0.2.0. The 0.3.0 importer prepares blocked, unassigned native families with revision-pinned source and readiness documents; its isolated qualification is complete. Paperclip documents remain natively mutable; consumers verify the retained revision and hash. A source_observed result is stored source evidence, and even prepared does not grant Council admission. See the versioned readiness contract.

The opt-in Council receiver validates an enabled revisioned project mandate, prepares explicit contributor assignments and council-work.ownedPaths, and preserves done/cancelled history. Fresh source attestations are required before preparation and initial admission. Later remote Linear changes do not automatically revoke an admitted mission; Council retains its pinned native source, mandate and budget gates.

First scope

• One explicitly configured Linear workspace/team/project and its exact Todo workflow-state ID, mapped to one Paperclip company/project.
• A parent entering Todo selects its remaining descendant work; a child entering Todo selects its own subtree and does not authorize its siblings.
• Reuse Paperclip's managed Linear MCP connection, plugin webhooks, jobs, secrets, storage, tasks, documents, relations, and events where their contracts cover the required behavior.
• Use the official GraphQL API only for source reads that the verified managed connector cannot provide.
• Preserve Linear identity, descriptions, hierarchy, blockers, and historical results. Duplicate deliveries and restarts must not create a second launch.
• Import and admission run without a model call. Any planning needed from the implementation lead belongs to the workflow's existing authorized budget.

Slack, Linear status writeback, merge, deployment, and Paperclip core changes remain outside this source/import lot. Fixed milestone campaigns are available only through the separately enrolled, disabled-by-default V1 path described above.

Documents

• Architecture and ownership
• Todo import and handoff contract
• Implementation sequence and acceptance checks
• Council receiver qualification and limits
• Repository working instructions

The Council integration is a separate dependency. Its qualified 0.7.18 receiver accepts this exact imported origin only under an explicit project mandate with source scope, contributor assignments and write paths. Readiness, a fresh source observation and Council's existing accounting are all required. Initial qualification covers a subtree with executable descendants; roots with no executable descendant and external source blocker references remain blocked for an explicit operator decision. Operational launch remains disabled.