feat(sdk): linear-poller — second proactive workload for gate 2 (Track E)

[kjgbot]

Track E — Linear as the second proactive workload

RFC-0001 §3 gate 2 says the workload can be "hn-monitor OR linear." Track A is landing hn-monitor; this adds Linear so we prove the pattern generalizes to more than one adapter.

Zero overlap with Track A. This PR only adds NEW files under `sdk/src/linear-poller.ts`, `sdk/tests/linear-poller.test.ts`, `testdata/linear-monitor.flow.yaml`, plus 3 lines added to `sdk/src/index.ts`. No conflict with `hn-monitor-runner` work in flight on Track A.

What this ships

• `sdk/src/linear-poller.ts` (~120 lines) — `pollLinearOnce()` calls the Linear GraphQL endpoint, submits each new issue as a `linear.issue_created` event. Same shape as `hn-poller.ts`. Fail-closed on missing token, GraphQL errors, and malformed responses.
• `sdk/tests/linear-poller.test.ts` (~95 lines) — 6 tests, all use injected fetcher (never touch the network).
• `testdata/linear-monitor.flow.yaml` — flow spec with `linear.issue_created` trigger, dedupe by `payload.id`, one agent step that triages the issue (priority/size/first_action).
• `sdk/src/index.ts` — exports.

Non-goals for this PR

• Runner: the composing runner lives on Track A (`HnMonitorRunner` in PR feat(sdk): HnMonitorRunner — continuous hn-monitor polling with worker attach (sub-PR A) #85). Once its shape lands, a `LinearMonitorRunner` is trivial — it's generic over the poller. Not this PR.
• Canonical spec JSON: `testdata/linear-monitor.spec.canonical.json` will be produced by the compile step when the runner uses this flow. Not this PR.
• Auth: uses `LINEAR_API_TOKEN` env var as bootstrap. Gate 6 (relayfile-mounted credentials) replaces this later. Not this PR.

Test results

```
$ npx vitest run tests/linear-poller.test.ts
Test Files 1 passed (1)
Tests 6 passed (6)
```

FAIL-first evidence

• Source removed: `sdk/src/linear-poller.ts` moved aside → test file failed to load. Tests: no tests.
• Source restored: Tests 6 passed (6).

Test plan

• All 6 tests pass
• FAIL-first evidence captured
• Fail-closed on missing token, GraphQL errors, malformed responses
• createdAfter filter forwarded to GraphQL query
• Zero overlap with Track A / D (new files only, one 3-line addition to index.ts)
• Swarm review (this PR)

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: a99af6f6-d412-44d1-aa57-1d06efe67361

📥 Commits

Reviewing files that changed from the base of the PR and between 08d2d33 and cd5a9a9.

📒 Files selected for processing (4)

• sdk/src/index.ts
• sdk/src/linear-poller.ts
• sdk/tests/linear-poller.test.ts
• testdata/linear-monitor.flow.yaml

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The SDK adds a Linear GraphQL polling adapter that emits linear.issue_created events. It exports the adapter API, adds unit tests for polling behavior, and adds a workflow that triages new Linear issues.

Changes

Linear integration

Layer / File(s)	Summary
Linear poller and SDK exports sdk/src/linear-poller.ts, sdk/src/index.ts	Defines polling contracts and options, authenticates with an explicit token or LINEAR_API_TOKEN, fetches and validates Linear issues, submits journal events, and exports the adapter API.
Poller behavior validation sdk/tests/linear-poller.test.ts	Tests event mapping, authentication failures, GraphQL errors, malformed responses, createdAfter filtering, and the exported endpoint.
Linear issue triage workflow testdata/linear-monitor.flow.yaml	Triggers on deduplicated linear.issue_created events, runs issue triage with reset recovery, and validates the JSON result schema.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to cd5a9

Adds a Linear polling adapter, its flow fixture, tests, and public exports without introducing an actionable merge-blocking risk; it is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant LinearPoller
  participant LinearGraphQL
  participant JournalSink
  participant LinearMonitor
  LinearPoller->>LinearGraphQL: Request recent issues
  LinearGraphQL-->>LinearPoller: Return issue data
  LinearPoller->>JournalSink: Submit linear.issue_created events
  JournalSink->>LinearMonitor: Trigger issue triage
  LinearMonitor-->>JournalSink: Store validated triage result

Loading

Poem

A rabbit polls where Linear flows,

Finds fresh issues in neat rows.
Events hop into the journal bright,
Triage sorts each task just right,
And tests guard the path it knows.

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/settings/billing.

_{Comment @coderabbitai help to get the list of available commands.}

[kjgbot]

maintainability lens — FAIL

Maintainability review — PR #89 (linear-poller)

The adapter mirrors hn-poller.ts cleanly and the "why it lives outside kernel/" doc block is genuinely useful. Three things a future maintainer would trip over:

Blockers

1. GraphQL query is built by string interpolation over caller-supplied values — linear-poller.ts:100-114. Both issueLimit (number, no bounds check) and createdAfter (string, no format check) are pasted directly into the query. A caller who passes createdAfter = '2026-01-01\" } } y { z: \"' breaks the query; a caller who passes issueLimit = 10.5 or NaN produces invalid GraphQL. This is a hidden contract on the public function signature (PollOptions.createdAfter: string) and it will bite the first person who wires this to an external timestamp. Use GraphQL variables (query ($after: DateTimeOrDuration) { … filter: { createdAt: { gt: $after } } }) and pass them in the JSON body — same idiom Linear's own SDK uses, and it removes both hazards.

Concerns

2. orderBy: createdAt doesn't state direction — linear-poller.ts:103. The docstring says "newest issues" but the query doesn't say that; the reader has to know Linear's PaginationOrderBy defaults. Either add an inline comment // PaginationOrderBy is DESC by default in Linear or make it explicit. A silent change on Linear's side would flip the sampling window without a test failure.

3. Implicit payload.type = 'issue' coupling — linear-poller.ts:139 sets type: 'issue' solely so the flow's pattern: { type: issue } (testdata/linear-monitor.flow.yaml:11-12) matches. This is the same pattern as hn-poller, but neither side comments why the field exists. A flow author who drops pattern.type gets silent behavior change; a poller author who drops payload.type gets silent trigger failure. One sentence on either side, or a shared constant, would save the next reader.

4. Test that "wouldn't fail if the behavior broke" — linear-poller.test.ts:100-102 asserts only that LINEAR_GRAPHQL_ENDPOINT === 'https://api.linear.app/graphql'. Since the constant is a literal in the same module, this pins the string, not the behavior. If someone points the fetcher elsewhere, this test still passes. Either drop it or assert the default fetcher hits that URL.

Notes

5. linear-poller.test.ts:47 comment "Vitest per-file workers make this safe" — file-level isolation, not per-test; harmless here (tests inject token: 't') but the note is misleading.

6. GraphQL partial-success responses ({ data, errors }) throw and discard data (linear-poller.ts:126-128). Intentional fail-closed, but undocumented — worth one line.

REVIEW_FAILED

[kjgbot]

history lens — FAIL

Blocker

PR #89 introduces a new contradiction with RFC-0001 settled decision #1. The SDK now owns Linear-specific transport, authentication, GraphQL construction, and response parsing in sdk/src/linear-poller.ts:24-46 and sdk/src/linear-poller.ts:75-124, then publicly exports that implementation as a “Linear adapter” in sdk/src/index.ts:147-156. RFC-0001 §6 assigns providers to relayfile adapters; Gate 6 further requires that adding a provider require zero relayflows code. Keeping this outside kernel/ respects PR #16, but it does not satisfy the later, broader settled boundary. This is newly added provider ownership, not untouched scaffolding.

The documented deferral covers credentials—moving LINEAR_API_TOKEN to a relayfile-mounted credential—and the runner. It does not say the direct Linear client itself will move out of the SDK. To clear the blocker, Linear ingress should come through relayfile’s adapter/webhook boundary, leaving this repository with only the provider-neutral event/journal interface.

Concerns

The “second proactive workload” and “proves the pattern generalizes” claims in sdk/src/linear-poller.ts:9-11 and testdata/linear-monitor.flow.yaml:3-6 are premature: this PR contains no runner, production trigger, liveness check, or canonical bundle. Because the PR explicitly defers the runner and canonical spec, that overstatement is non-blocking under the scaffolding rule.

The commit’s four-file scope matches the diff, and six tests exist at sdk/tests/linear-poller.test.ts:29-101. Its FAIL-first claim lacks literal command/output, while the approximate file-size claims are loose—149 lines described as ~120 and 102 as ~95. Those are evidence-quality concerns, not demonstrated untruths.

Notes

I found no DRIVE-LOG-recorded mistake that this diff reintroduces; it also leaves kernel/ untouched.

REVIEW_FAILED

[kjgbot]

structure lens — PASS

→ Read docs/RFC-0001-everything-is-a-relayflow.md
→ Read sdk/src/hn-poller.ts

$ ls /Users/khaliqgant/AgentWorkforce/flows-ops/sdk/src/
backlog-picker.ts
canonical.ts
cli
cli.ts
compile.ts
demo-hn-monitor.ts
failure-kinds.ts
hn-poller.ts
index.ts
journal-client.ts
preflight.ts
protocol.ts
spec.ts
validate.ts
work-package-consumer.ts
work-package-validator.ts
worker.ts

✱ Grep "EventSink" in sdk · 5 matches
→ Read sdk/src/protocol.ts

Structure review — PR #89 (Linear adapter)

The change is a faithful copy of the settled hn-poller pattern (PR #16) and stays on the right side of the line that review has drawn before: adapter lives in sdk/, never kernel/, and the kernel learns about Linear only through event.submit. The 149-line file is single-purpose and well under the 500-line smell threshold. Fail-closed discipline holds in all the right places — missing token throws (linear-poller.ts token guard), GraphQL errors throw, malformed data.issues.nodes throws. No product logic, no network I/O, no tenant awareness, no new step verb introduced into the kernel. That is all correct and matches RFC-0001 gate 2's "hn-monitor or linear" wording precisely.

Concerns

1. EventSink re-declares the protocol boundary — and is now duplicated a second time. sdk/src/protocol.ts already owns the event.submit surface: EventSubmitParams ({ spec, event: { type, payload, key } }) and EventSubmitResult ({ matched, deduped }). linear-poller.ts hand-rolls a near-identical eventSubmit(spec, event): Promise<unknown> interface — the same one already copy-pasted in hn-poller.ts:21. That Promise<unknown> erases the kernel's typed result, so the adapter cannot observe whether it was deduped. This is exactly the "nothing reaches around [the journal protocol]" concern in AGENTS.md rule 3 and RFC decision 13 (helpers over primitives). This is the moment to extract one shared EventSink (returning EventSubmitResult) before a third adapter arrives. Not a correctness bug today, but a drift surface.

2. async/any casts and unescaped filter interpolation. (parsed as any)?.data?.issues?.nodes and (parsed as any).errors weaken the shape check the tests otherwise enforce well. The createdAfter value is string-interpolated directly into the GraphQL filter (gt: "${createdAfter}") with no escaping — safe for the author's own ISO timestamps, but worth a note.

3. Duplicate PollOptions export. index.ts maps PollOptions as LinearPollOptions to dodge a collision with hn-poller's PollOptions — the collision itself signals the shared-abstraction gap in concern 1.

Notes

• testdata/linear-monitor.flow.yaml is coherent: trigger linear.issue_created matches the submitted event type; pattern: type: issue matches payload.type; dedupeKeyTemplate on payload.id is stable. Step is type: agent with recoveryMode: reset, matching RFC Appendix A.

The adapter is structurally correct; the review should not block on it — but concern 1 should be turned into the single shared EventSink helper in protocol.ts before it spreads further.

REVIEW_PASSED

[kjgbot]

🎯 review-swarm: FAILED (M:fail H:fail S:pass)

Lens transcripts posted as sibling comments above.

[kjgbot]

Track E was misconceived. RFC-0001 §6 assigns providers to relayfile adapters (gate 6), not SDK code — hn-poller is grandfathered but adding Linear the same way would regress the settled decision (swarm history lens caught this correctly). Replacing with a non-provider second workload (dir-watcher) that proves the runner pattern without introducing new provider code.