@exaudeus/workrail 3.32.0 → 3.33.0

package/docs/design/github-polling-adapter-design-candidates.md

@@ -0,0 +1,226 @@
+# GitHub Polling Adapter: Design Candidates
+
+**Date:** 2026-04-15
+**Type:** Design Candidates
+**Status:** Draft -- for review
+
+---
+
+## Problem Understanding
+
+### The Ask
+
+Add GitHub Issues and GitHub PRs polling adapters that mirror the GitLab adapter pattern. Poll GitHub APIs on a configurable schedule, deduplicate via `PolledEventStore`, dispatch workflows via `TriggerRouter.dispatch()`. Must include `excludeAuthors` filter to prevent self-review loops.
+
+### Infrastructure Context
+
+The GitLab adapter infrastructure lives in the `feat-polling-triggers` worktree (PR #404, in-flight). It is NOT merged to `main` yet. The GitHub adapter work must be built on top of that branch. Files in scope:
+
+- `src/trigger/adapters/gitlab-poller.ts` -- the direct template
+- `src/trigger/polling-scheduler.ts` -- orchestration; calls adapters and dispatches
+- `src/trigger/polled-event-store.ts` -- per-trigger deduplication state on disk
+- `src/trigger/types.ts` -- `GitLabPollingSource`, `TriggerDefinition.pollingSource`
+- `src/trigger/trigger-store.ts` -- YAML parser, `SUPPORTED_PROVIDERS` set
+
+### Core Tensions
+
+**1. Shared `source:` YAML block vs. type-safe discriminated union.**
+The YAML parser uses one `source:` block with shared field names. GitLab uses `projectId`; GitHub uses `repo`. If reusing the same block, the raw parsed type is a union of optional fields -- structurally looser than the assembled typed model. The discriminated union only kicks in after assembly; the raw parser type cannot be discriminated cleanly.
+
+**2. `pollingSource` field migration vs. backward compatibility.**
+The current `TriggerDefinition.pollingSource?: GitLabPollingSource` field has a code comment requesting migration to a discriminated union at adapter #2 (this change). All existing narrowing in `polling-scheduler.ts` and `trigger-store.ts` must be updated. The impact surface is small but must be handled atomically.
+
+**3. GitHub PR `updated_at` vs. GitLab `updated_after` API semantics.**
+GitLab issues endpoint accepts `updated_after=<ISO8601>` as a server-side filter. GitHub PRs endpoint does NOT accept a `since` parameter -- must fetch all open PRs sorted by `updated` desc, then filter client-side where `updated_at > lastPollAt`. This means more items are fetched per cycle and the deduplication load shifts to the client.
+
+**4. `notLabels` client-side filter vs. pagination.**
+GitHub API supports `labels=foo,bar` (include filter) but has no native exclude. The `notLabels` filter runs client-side. But with only 100 items per page and no pagination, filtering out many items means some new items may be missed. Accepted limitation -- same as the GitLab adapter's pagination limitation.
+
+### What Makes This Hard
+
+A junior developer would:
+1. Skip the discriminated union migration and leave `pollingSource` as a bare `GitLabPollingSource | GitHubPollingSource` union -- the compiler cannot enforce which source type accompanies which provider string
+2. Forget to add `github_issues_poll` and `github_prs_poll` to `SUPPORTED_PROVIDERS` in `trigger-store.ts` -- triggers would silently fail with `unknown_provider` at config load
+3. Use `lastPollAt` as a GitHub PRs `since` parameter (the API ignores it -- no such parameter exists for PRs)
+4. Miss the rate limit header check -- at 5000 req/hour the math is fine for normal use, but a burst or misconfiguration could exhaust it without warning
+5. Place the `excludeAuthors` filter AFTER the dispatch call, creating the self-loop it was meant to prevent
+
+### Likely Seam
+
+`polling-scheduler.ts` is the coordination point. It must route to the correct adapter based on `trigger.provider`. The current code calls `pollGitLabMRs` directly -- this must become provider-aware dispatch.
+
+---
+
+## Philosophy Constraints
+
+From `CLAUDE.md` (hard rules):
+
+- **Errors are data** -- all public functions return `Result<T, E>`, never throw
+- **Immutability by default** -- all types `readonly`, all interfaces use `readonly` fields
+- **Make illegal states unrepresentable** -- the TODO in `types.ts` for discriminated union is exactly this principle; the union migration fulfills it
+- **Validate at boundaries, trust inside** -- `trigger-store.ts` validates all fields at parse time; adapters receive already-validated config
+- **Type safety as first line of defense** -- branded `TriggerId`, explicit `Result` types, type guards
+- **Dependency injection for boundaries** -- `fetchFn` is injectable in `gitlab-poller.ts`; required for the GitHub adapter too
+- **Prefer fakes over mocks** -- tests use `vi.fn().mockResolvedValue()` for fetch; maintain this pattern
+- **YAGNI with discipline** -- no registry pattern (premature for 2 providers)
+
+**Philosophy conflict:** The backlog example uses `excludeAuthors: "worktrain-*"` suggesting glob matching. The `CLAUDE.md` principle of determinism and the YAML parser's lack of glob support argue for exact string matching only. **Resolution:** exact string match for MVP; glob support is a documented TODO.
+
+---
+
+## Impact Surface
+
+Files that must remain consistent:
+
+- `src/trigger/types.ts` -- type shape changes here cascade to the assembler and scheduler
+- `src/trigger/trigger-store.ts` -- `SUPPORTED_PROVIDERS`, `ParsedTriggerRaw.source`, assembly code
+- `src/trigger/polling-scheduler.ts` -- `isPollingTrigger`, `buildWorkflowTrigger`, `doPoll` routing
+- `tests/unit/trigger-store.test.ts` -- tests for `github_issues_poll` and `github_prs_poll` providers
+- `tests/unit/gitlab-poller.test.ts` -- template; existing tests must continue to pass
+
+No other files outside `src/trigger/` read `pollingSource` today.
+
+---
+
+## Candidates
+
+### Candidate A: Minimal extension -- bare union type, if/else in scheduler
+
+**Summary:** Add `GitHubPollingSource` to `types.ts` as a bare union (`pollingSource?: GitLabPollingSource | GitHubPollingSource`), add new providers to `SUPPORTED_PROVIDERS`, extend the `source:` parser, add `if/else` branches in `PollingScheduler.doPoll`.
+
+**Tensions resolved:** Zero migration cost. No changes to existing narrowing code.
+
+**Tensions accepted:** The discriminated union TODO is ignored. TypeScript cannot prevent a `GitLabPollingSource` being used with a `github_issues_poll` trigger at the assembled type level. Illegal states remain representable.
+
+**Boundary solved at:** `polling-scheduler.ts` routing -- additive `if/else` only.
+
+**Why this boundary:** Minimum change surface.
+
+**Failure mode:** A future refactor could accidentally call `pollGitLabMRs` with a `GitHubPollingSource` because the compiler cannot distinguish them without the tag. Silent wrong behavior, not a compile error.
+
+**Repo-pattern relationship:** Adapts existing pattern but ignores the explicit codebase TODO for discriminated union.
+
+**Gains:** Zero migration cost, zero risk of breaking existing code.
+
+**Losses:** Correctness guarantee at the type level. The codebase's own comment requests this migration.
+
+**Impact surface:** `polling-scheduler.ts` only (additive). `types.ts` additive.
+
+**Scope judgment:** Correct scope, but incomplete honoring of stated invariants.
+
+**Philosophy fit:** Honors YAGNI. Violates "Make illegal states unrepresentable".
+
+---
+
+### Candidate B: Tagged union migration (RECOMMENDED)
+
+**Summary:** Migrate `TriggerDefinition.pollingSource` to a discriminated union tagged by `provider`:
+
+```ts
+export type PollingSource =
+  | (GitLabPollingSource & { readonly provider: 'gitlab_poll' })
+  | (GitHubPollingSource & { readonly provider: 'github_issues_poll' })
+  | (GitHubPollingSource & { readonly provider: 'github_prs_poll' });
+```
+
+`trigger-store.ts` assembler produces the tagged object (adds `provider` field to the assembled source). `polling-scheduler.ts` uses `switch(trigger.pollingSource.provider)` or typed `if/else` on `provider` to narrow. `github-poller.ts` is a pure function matching the GitLab adapter signature.
+
+**Tensions resolved:** Discriminated union TODO fulfilled. Illegal states unrepresentable at the assembled type level. `switch` on `provider` is compiler-enforced exhaustive.
+
+**Tensions accepted:** Small migration: ~20 lines of changes in existing files. The raw `ParsedTriggerRaw.source` type in `trigger-store.ts` is still an untagged bag of optional fields (the discrimination only applies after assembly, not during parsing).
+
+**Boundary solved at:** `types.ts` (new union), `trigger-store.ts` (tagged assembly), `polling-scheduler.ts` (switch routing).
+
+**Why this boundary is best fit:** The `types.ts` comment explicitly requests this migration at adapter #2. This IS adapter #2. Not doing it defers a known debt item.
+
+**Failure mode:** If a future consumer outside `src/trigger/` reads `pollingSource` and was not updated during migration. Verified: no such consumer exists today.
+
+**Repo-pattern relationship:** Directly follows what the codebase's own TODO comment requests. Mirrors `TriggerId` branded string: same philosophy of making types carry guarantees.
+
+**Gains:** Compile-time guarantee that GitLab source never reaches the GitHub adapter. Exhaustive `switch` on provider. Clean type-level documentation of which sources exist.
+
+**Losses:** ~20 lines of existing code must be updated. The `pollingSource` field shape changes.
+
+**Impact surface:** `trigger-store.ts` assembler, `polling-scheduler.ts` narrowing, `types.ts`. No external consumers.
+
+**Scope judgment:** Best-fit -- the TODO explicitly scopes this to adapter #2.
+
+**Philosophy fit:** Honors "Make illegal states unrepresentable", "Type safety as first line of defense", "Exhaustiveness everywhere". Minor YAGNI tension (resolved by the existing TODO).
+
+---
+
+### Candidate C: Generic `PollingAdapter` interface with registry
+
+**Summary:** Define `interface PollingAdapter<TItem, TSource>` with `poll(source: TSource, since: string, fetchFn?) => Result<TItem[], error>`. A registry `Map<string, PollingAdapter<unknown, unknown>>` holds all adapters. The scheduler looks up by `trigger.provider`. Adding a new provider = registering a new adapter; no scheduler changes.
+
+**Tensions resolved:** Open/closed: adding providers requires zero scheduler changes. Perfect separation of concerns.
+
+**Tensions accepted:** The registry carries `unknown` typed adapters. The scheduler must cast when building `WorkflowTrigger` context -- type safety lost at the registry boundary. Runtime invariant, not compile-time.
+
+**Boundary solved at:** New `adapter-registry.ts`. Scheduler depends on registry, not specific adapters.
+
+**Why this boundary:** Maximum extensibility for future providers.
+
+**Failure mode:** A misregistered adapter (wrong source type registered under wrong provider key) silently produces wrong context at dispatch time. No compile-time catch.
+
+**Repo-pattern relationship:** Departs from existing patterns. Codebase has no registry or DI container for adapters. Introduces a new abstraction not justified by existing use.
+
+**Gains:** Maximum extensibility (Jira, Linear, Sentry adapters add zero scheduler code).
+
+**Losses:** Type safety at the registry boundary. Complexity for 2 providers. Violates YAGNI and the explicit CLAUDE.md warning against speculative abstractions.
+
+**Impact surface:** New `adapter-registry.ts`, changes to `polling-scheduler.ts`, new abstract type in `types.ts`.
+
+**Scope judgment:** Too broad -- 2 providers do not justify a registry.
+
+**Philosophy fit:** Violates YAGNI, violates "Type safety as first line of defense". Honors open/closed but prematurely.
+
+---
+
+## Comparison and Recommendation
+
+**Recommendation: Candidate B (tagged union migration)**
+
+| Dimension | A (minimal) | B (tagged union) | C (registry) |
+|---|---|---|---|
+| Illegal states representable | Yes (bug risk) | No (compile-time) | Partially (cast gap) |
+| Migration cost | Zero | ~20 lines | High |
+| Exhaustive narrowing | No | Yes | No |
+| YAGNI | Honors | Minor (TODO overrides) | Violates |
+| Consistent with TODO | No | Yes | No |
+| Future extensibility | If/else grows | Union grows | Registry extends |
+
+Candidate B is the correct choice for three reasons:
+
+1. **The TODO is a commitment.** `types.ts` already says "TODO(follow-up): migrate to discriminated union at adapter #2." This is adapter #2. Skipping this is explicitly deferring committed technical debt.
+2. **The migration cost is bounded.** `pollingSource` is only read inside `src/trigger/`. No external consumers. The ~20 lines of changes are confined to three files.
+3. **The gain is real.** The `switch(pollingSource.provider)` pattern gives the TypeScript compiler full narrowing -- it is impossible to call `pollGitLabMRs` with a `GitHubPollingSource` after this change. Candidate A has no equivalent safety.
+
+---
+
+## Self-Critique
+
+**Strongest argument against B:** The raw `ParsedTriggerRaw.source` type in `trigger-store.ts` is still an untagged bag of optional fields -- both `projectId` (GitLab) and `repo` (GitHub) fields exist in the same raw type. The discriminated union only applies after assembly. So the "illegal states unrepresentable" benefit does NOT apply during YAML parsing -- only after. Candidate A has identical parse-time behavior. The union migration adds safety only at dispatch time.
+
+Counter-counter: dispatch time is where safety matters. The assembler is the parser boundary. After the assembler, the system should be able to trust the types -- that's where the discriminated union matters.
+
+**Narrower option that almost works:** Candidate A with a runtime assertion in the scheduler: `assert(trigger.provider === 'gitlab_poll')` before calling `pollGitLabMRs`. But TypeScript structural typing means both source types share enough optional fields that the assert is not enforced by the compiler -- it's a runtime check, not a compile-time one.
+
+**Broader option that might be justified:** Candidate C (registry), but only if 4+ providers are added within 6 months. At 2 providers, the registry is premature. Evidence required: 3+ new adapter types confirmed in the near-term roadmap.
+
+**Pivot conditions:**
+- If `pollingSource` is used outside `src/trigger/` in a future PR (expands migration scope)
+- If the `excludeAuthors` exact-string match is insufficient for the WorkTrain bot naming convention (requires glob support)
+- If the GitHub rate limit at 5000 req/hour proves insufficient for high-volume repos (requires backoff strategy)
+
+---
+
+## Open Questions for the Main Agent
+
+1. **`excludeAuthors` matching**: Should it be exact string match (e.g., `worktrain-bot`) or glob pattern (e.g., `worktrain-*`)? The backlog example uses `worktrain-*`. Exact match is simpler and safer for MVP.
+
+2. **`repo` field format**: Should it be `owner/repo` (single string, split at `/`) or two separate fields `owner` and `repo`? Single string `owner/repo` is consistent with how GitHub URLs work and matches the GitLab `projectId: namespace/project` pattern.
+
+3. **Rate limit skip**: When `X-RateLimit-Remaining < 100`, should this be a `GitHubPollError` kind or a silent skip (log only)? The prompt says "skip the current cycle and log a warning" -- so log only, no error return. Confirm this matches desired behavior.
+
+4. **`notLabels` documentation**: The pagination limitation means `notLabels` can silently miss items on busy repos. Should this be documented in the config schema comment, or is it acceptable as an implicit limitation?

package/docs/design/github-polling-adapter-design-review-findings.md

@@ -0,0 +1,131 @@
+# GitHub Polling Adapter: Design Review Findings
+
+**Date:** 2026-04-15
+**Design reviewed:** Candidate B -- tagged `PollingSource` discriminated union
+**Status:** Complete
+
+---
+
+## Tradeoff Review
+
+### Tradeoff 1: Parse-time raw type is still untagged (accepted)
+
+The `ParsedTriggerRaw.source` bag holds both `projectId` (GitLab) and `repo` (GitHub) as optional fields. Discrimination only applies after assembly. This is valid: the assembler validates required fields with explicit `missing_field` errors. A `github_issues_poll` trigger with `projectId` instead of `repo` will fail at assembly with a clear error.
+
+**Hidden assumption verified:** The assembler must explicitly validate `repo` as required for `github_issues_poll`/`github_prs_poll` (not inherited from GitLab path). Must be in the implementation.
+
+### Tradeoff 2: `excludeAuthors` exact string match (accepted)
+
+Valid for a single controlled bot account. Breaks if the bot naming convention uses unpredictable suffixes. Mitigated by: prominent warning in `GitHubPollingSource` comment, TODO for glob support.
+
+### Tradeoff 3: 100 items per page, no pagination (accepted)
+
+Issues API has native `since` filter -- pagination almost never needed. PRs API lacks `since` -- all open PRs fetched and filtered client-side. Burst risk (>100 PRs in one interval) is low for typical repos. Must be documented.
+
+### Tradeoff 4: GitHub PRs client-side `updated_at` filter (accepted)
+
+Higher API cost per cycle (fetch up to 100 PRs vs. only updated ones). Within rate limit budget at normal poll intervals (42 req/hour for PRs at 5-min interval). Rate limit check guards the threshold.
+
+---
+
+## Failure Mode Review
+
+### RED: Self-loop if `excludeAuthors` not configured
+
+**Risk level:** HIGH. An unconfigured `excludeAuthors` creates an infinite loop: WorkTrain PR -> poll picks it up -> workflow dispatched -> another PR -> repeat. Cascading effects: rate limit exhaustion, unbounded sessions, potential cost impact.
+
+**Current mitigation:** None (it's optional config). User must explicitly set it.
+
+**Required mitigation:**
+- `GitHubPollingSource.excludeAuthors` comment must contain: "IMPORTANT: include your WorkTrain bot account login here to prevent infinite self-review loops."
+- `polling-scheduler.ts` dispatch path comment must repeat the warning.
+- A default auto-detection TODO (WorkTrain could know its own GitHub login) should be filed.
+
+### ORANGE: Rate limit skip has no alerting beyond log line
+
+**Risk level:** Medium. When `X-RateLimit-Remaining < 100`, the cycle is silently skipped with only a console warning. Users who don't monitor logs may not notice the adapter has stopped polling.
+
+**Current mitigation:** Log warning per skipped cycle.
+
+**Recommended mitigation:** No code change needed for MVP, but the log message should include the `X-RateLimit-Reset` timestamp so users know when polling will resume.
+
+### YELLOW: >100 PRs in one poll interval causes silent miss
+
+**Risk level:** Low for typical repos, medium for dependency-bot-heavy repos.
+
+**Mitigation:** Document in `GitHubPollingSource.pollIntervalSeconds` comment. No code change.
+
+### YELLOW: `excludeAuthors` exact match may be insufficient for numbered bot accounts
+
+**Risk level:** Low -- most bot accounts have stable names.
+
+**Mitigation:** TODO comment for glob support. No code change.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Candidate A (bare union + if/else):** Identified one borrow -- using `trigger.provider` for the dispatch switch is valid, but inside the switch arm TypeScript still needs the tag on `pollingSource` to narrow from `GitLabPollingSource | GitHubPollingSource` to the specific type. The hybrid (trigger.provider switch + untagged union) would require unsafe casts. Not worth pursuing.
+
+**Merged `github_poll` provider:** Rejected. Issues and PRs have different endpoints, different shapes, different filter semantics. Merging adds conditional logic to the adapter. Two single-purpose adapters are cleaner.
+
+**Simpler tagged union (add tag to source, but skip updating `isPollingTrigger` guard):** Already analyzed -- `isPollingTrigger` works unchanged when `pollingSource` becomes `PollingSource`. No simplification available.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|---|---|
+| Errors are data | Satisfied -- Result<T,E> everywhere |
+| Immutability by default | Satisfied -- all fields readonly |
+| Make illegal states unrepresentable | Satisfied -- tagged union |
+| Type safety as first line of defense | Satisfied -- type guards at boundary |
+| Validate at boundaries, trust inside | Satisfied -- assembler validates |
+| Dependency injection for boundaries | Satisfied -- fetchFn injectable |
+| Prefer fakes over mocks | Satisfied -- vi.fn() fake pattern |
+| Document why not what | Satisfied -- invariant comments required |
+| YAGNI | Minor tension -- overridden by existing TODO |
+| Determinism over cleverness | Minor tension -- excludeAuthors exact match acceptable |
+
+---
+
+## Findings
+
+### RED
+
+**Self-loop risk is not mitigated by default.** `excludeAuthors` is optional config with no default. A WorkTrain PR polling trigger with no `excludeAuthors` creates an infinite loop. The design must include prominent warnings in the `GitHubPollingSource` type comment and in the `polling-scheduler.ts` dispatch path comment.
+
+### ORANGE
+
+**Rate limit skip log message should include reset time.** When `X-RateLimit-Remaining < 100`, include `X-RateLimit-Reset` (Unix timestamp) in the log message so users know when polling resumes without digging into GitHub's documentation.
+
+### YELLOW
+
+**Both pagination and client-side filtering limitations must be documented in the type comment.** Not in code comments only -- in the `GitHubPollingSource` interface comment where users read it when configuring triggers.
+
+### YELLOW
+
+**`excludeAuthors` exact-match limitation must have a TODO for glob support.** The backlog example uses `worktrain-*` which implies glob. The implementation note should clarify that this is exact match and reference the backlog entry.
+
+---
+
+## Recommended Revisions
+
+1. **Add self-loop warning to `GitHubPollingSource.excludeAuthors` field comment** (required, not optional). Example text: "IMPORTANT: always include your WorkTrain bot account login here (e.g., `worktrain-bot`). Omitting this causes an infinite self-review loop where WorkTrain reviews its own PRs."
+
+2. **Include `X-RateLimit-Reset` in the rate limit skip log message.** Change: `console.warn('[GH] Rate limit low: remaining=${remaining}')` to `console.warn('[GH] Rate limit low: remaining=${remaining}, resets at ${new Date(resetTs * 1000).toISOString()}')`.
+
+3. **Document pagination limitation and client-side filter in `GitHubPollingSource` comments** -- one sentence each.
+
+4. **Add TODO for glob support in `excludeAuthors` comment** -- "TODO: exact string match only. Glob support (e.g., worktrain-*) planned but not implemented."
+
+---
+
+## Residual Concerns
+
+- **`github_prs_poll` redundancy with `github_issues_poll`:** GitHub Issues API returns PRs as well (a PR is also an issue). Using `github_issues_poll` with `labelFilter: my-label` could accidentally pick up PRs. Users should be aware that `state=open` on the issues endpoint includes open PRs. The `github_prs_poll` adapter uses the separate `/repos/:owner/:repo/pulls` endpoint which is PR-only. Both adapters should document this distinction.
+
+- **Authentication:** Only personal access tokens are supported (same as GitLab). GitHub App tokens and fine-grained PATs are not addressed. This is an accepted MVP limitation.
+
+- **`filter.notLabels` naming:** The backlog uses `filter.notLabels` as a nested object. The implementation uses `notLabels` as a top-level field on `GitHubPollingSource` for simplicity (consistent with how `events` and `labelFilter` are flat fields). No structural concern but naming should be consistent with any future filter fields.

package/docs/design/github-polling-adapter-implementation-plan.md

@@ -0,0 +1,284 @@
+# GitHub Polling Adapter: Implementation Plan
+
+**Date:** 2026-04-15
+**Branch:** `feat/github-polling-adapter` (based on `feat-polling-triggers`)
+**Status:** Ready for implementation
+
+---
+
+## 1. Problem Statement
+
+WorkRail can poll GitLab MRs for new/updated merge requests (PR #404, in-flight). There is no equivalent for GitHub. Users with GitHub repos must configure webhooks (requiring admin access + public URL) or forgo event-driven automation entirely. This plan implements GitHub Issues and GitHub PRs polling adapters that mirror the GitLab pattern exactly: poll on a schedule, deduplicate via `PolledEventStore`, dispatch via `TriggerRouter.dispatch()`.
+
+---
+
+## 2. Acceptance Criteria
+
+1. A trigger with `provider: github_issues_poll` polls `GET /repos/:owner/:repo/issues?state=open&since=<ISO8601>&sort=updated` on the configured interval.
+2. A trigger with `provider: github_prs_poll` polls `GET /repos/:owner/:repo/pulls?state=open&sort=updated&direction=desc` and filters `updated_at > lastPollAt` client-side.
+3. Events authored by users in `excludeAuthors` are never dispatched.
+4. `notLabels` excludes items with matching labels (client-side filter).
+5. `labelFilter` is passed as `labels=` query parameter to the issues/pulls endpoint.
+6. When `X-RateLimit-Remaining < 100`, the poll cycle is skipped and a warning is logged with the reset timestamp.
+7. Items already processed (by ID) are not re-dispatched across daemon restarts (deduplication via `PolledEventStore`).
+8. `trigger-store.ts` parses `github_issues_poll` and `github_prs_poll` triggers from `triggers.yml` with all required fields validated.
+9. `TriggerDefinition.pollingSource` is typed as a tagged `PollingSource` discriminated union.
+10. All existing GitLab tests continue to pass unchanged.
+11. `github-poller.test.ts` covers: success, empty response, HTTP 401/500, network error, invalid JSON, non-array response, malformed items, event filter, `excludeAuthors`, `notLabels`, rate limit skip, URL construction.
+
+---
+
+## 3. Non-Goals
+
+- Pagination beyond 100 items per page
+- GitHub webhooks
+- GitHub App token or fine-grained PAT support
+- Glob pattern matching for `excludeAuthors`
+- Response caching or request coalescing
+- Monitoring or alerting beyond log messages
+- Configuring `notLabels` as a server-side filter (API does not support it)
+
+---
+
+## 4. Philosophy-Driven Constraints
+
+- All public functions return `Result<T, E>`. No throws at adapter boundaries.
+- All types are `readonly` on every field.
+- `fetchFn` is injectable in both adapter functions (required for tests).
+- Tests use `vi.fn().mockResolvedValue()` (fakes, not mocks of full HTTP layer).
+- Rate limit skip is a log-and-return, not an error result (per stated requirement).
+- `excludeAuthors` is exact string match only. Glob support filed as TODO.
+- At-least-once ordering: `dispatch()` BEFORE `store.record()`.
+
+---
+
+## 5. Invariants
+
+1. **At-least-once delivery**: dispatch is called BEFORE `PolledEventStore.record()`. If process crashes between dispatch and record, events re-fire. Silent miss is worse than duplicate.
+2. **Fresh-start invariant**: `PolledEventStore` initializes `lastPollAt=now` on missing/corrupt file. Never re-fires historical events on daemon restart.
+3. **Skip-cycle guard**: if a poll cycle is still running when the next interval fires, skip the new cycle. Never run two concurrent polls for the same trigger.
+4. **`excludeAuthors` filter runs BEFORE dispatch**. Never dispatch an event for a filtered author.
+5. **Rate limit skip**: if `X-RateLimit-Remaining < 100`, return early from the adapter (log warning). Do NOT call dispatch.
+6. **No silent schema rejection**: type guards (`isGitHubIssueShape`, `isGitHubPRShape`) skip malformed items and return valid ones; they do not return errors.
+7. **`github_issues_poll` and `github_prs_poll` must be in `SUPPORTED_PROVIDERS`** in `trigger-store.ts` or config parsing silently rejects them with `unknown_provider`.
+
+---
+
+## 6. Selected Approach + Rationale + Runner-Up
+
+**Selected: Candidate B -- tagged `PollingSource` discriminated union**
+
+```ts
+export type PollingSource =
+  | (GitLabPollingSource & { readonly provider: 'gitlab_poll' })
+  | (GitHubPollingSource & { readonly provider: 'github_issues_poll' })
+  | (GitHubPollingSource & { readonly provider: 'github_prs_poll' });
+```
+
+`TriggerDefinition.pollingSource` is typed as `PollingSource | undefined`. The assembler in `trigger-store.ts` adds the `provider` tag. The scheduler uses `switch(trigger.pollingSource.provider)` for exhaustive dispatch.
+
+**Rationale:** `types.ts` already has the comment "TODO: migrate to discriminated union at adapter #2." This is adapter #2. The migration is bounded to 3 files with no external consumers of `pollingSource`.
+
+**Runner-up: Candidate A** -- bare union without tag. Lost because TypeScript cannot narrow `GitLabPollingSource | GitHubPollingSource` inside a `switch(trigger.provider)` arm without unsafe casts. The tag is necessary for compiler-enforced safety.
+
+---
+
+## 7. Vertical Slices
+
+### Slice 1: Types -- `GitHubPollingSource` and `PollingSource` union
+
+**Files:** `src/trigger/types.ts`
+
+**Changes:**
+- Add `GitHubPollingSource` interface (fields: `baseUrl`, `repo`, `token`, `events`, `pollIntervalSeconds`, `excludeAuthors`, `notLabels`, `labelFilter`)
+- Add `PollingSource` discriminated union type
+- Change `TriggerDefinition.pollingSource?: GitLabPollingSource` to `pollingSource?: PollingSource`
+
+**Done when:** TypeScript compiles with no errors after the type change. All existing GitLab code that reads `pollingSource` still compiles (it will need narrowing updates in Slice 4).
+
+---
+
+### Slice 2: Trigger store -- parse `github_issues_poll` and `github_prs_poll`
+
+**Files:** `src/trigger/trigger-store.ts`
+
+**Changes:**
+- Add `'github_issues_poll'` and `'github_prs_poll'` to `SUPPORTED_PROVIDERS`
+- Add `repo`, `excludeAuthors`, `notLabels`, `labelFilter` to `ParsedTriggerRaw.source` optional fields
+- Add assembly branch in `validateAndResolveTrigger` for GitHub providers: validate `repo` required, validate `token` required, parse `excludeAuthors` space-separated, parse `notLabels` space-separated, parse `labelFilter` space-separated, produce tagged `PollingSource`
+- Add `provider` tag to the assembled GitLab source too (so `pollingSource.provider === 'gitlab_poll'` works)
+- Warn on unrecognized `source` fields for non-polling providers (existing behavior -- no change)
+
+**Done when:** `triggers.yml` with `provider: github_issues_poll` and a valid `source:` block parses without error. Missing `repo` returns `missing_field` error. `trigger-store.test.ts` updated tests pass.
+
+---
+
+### Slice 3: GitHub poller adapter
+
+**Files:** `src/trigger/adapters/github-poller.ts` (new)
+
+**Exports:**
+- `interface GitHubIssue` -- fields: `id`, `number`, `title`, `html_url`, `updated_at`, `state`, `user`, `labels`
+- `interface GitHubPR` -- fields: `id`, `number`, `title`, `html_url`, `updated_at`, `state`, `user`, `draft`
+- `type GitHubPollError` -- kinds: `http_error`, `network_error`, `parse_error`
+- `async function pollGitHubIssues(source, since, fetchFn?): Promise<Result<GitHubIssue[], GitHubPollError>>`
+- `async function pollGitHubPRs(source, since, fetchFn?): Promise<Result<GitHubPR[], GitHubPollError>>`
+
+**Issues endpoint:** `GET https://api.github.com/repos/:owner/:repo/issues?state=open&since=<since>&sort=updated&direction=desc&per_page=100&labels=<labelFilter>`
+
+**PRs endpoint:** `GET https://api.github.com/repos/:owner/:repo/pulls?state=open&sort=updated&direction=desc&per_page=100`
+
+**Both functions:**
+1. Build URL
+2. Fetch with `Authorization: Bearer <token>` header
+3. Check `X-RateLimit-Remaining` -- if < 100, log warning with reset timestamp, return `ok([])`
+4. On non-2xx: return `err({ kind: 'http_error', status, message })`
+5. Parse JSON array
+6. Apply `isGitHubIssueShape` / `isGitHubPRShape` type guard
+7. Filter `item.user?.login` against `source.excludeAuthors` (exact string match)
+8. For PRs only: filter `item.updated_at > since` (client-side)
+9. Apply `notLabels` filter: drop items where any label name is in `source.notLabels`
+10. Return `ok(items)`
+
+**Rate limit check implementation:**
+```ts
+const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') ?? '9999', 10);
+const resetTs = parseInt(response.headers.get('X-RateLimit-Reset') ?? '0', 10);
+if (remaining < 100) {
+  console.warn(`[GitHubPoller] Rate limit low: remaining=${remaining}, resets at ${new Date(resetTs * 1000).toISOString()}. Skipping cycle.`);
+  return ok([]);
+}
+```
+
+**Done when:** `github-poller.test.ts` passes all cases (success, errors, filters, rate limit skip).
+
+---
+
+### Slice 4: Polling scheduler -- extend for GitHub
+
+**Files:** `src/trigger/polling-scheduler.ts`
+
+**Changes:**
+- `isPollingTrigger` -- unchanged (still checks `pollingSource !== undefined`; type is now `PollingSource`)
+- `doPoll` -- change dispatch routing to `switch(trigger.pollingSource.provider)` with cases for `gitlab_poll`, `github_issues_poll`, `github_prs_poll`. No `default` case that silently drops -- use exhaustive check with a logged warning.
+- `buildWorkflowTrigger` -- split into:
+  - `buildGitLabWorkflowTrigger(trigger, mr: GitLabMR): WorkflowTrigger`
+  - `buildGitHubWorkflowTrigger(trigger, item: GitHubIssue | GitHubPR): WorkflowTrigger`
+
+**GitHub context variables injected:**
+```ts
+{
+  itemId: item.id,
+  itemNumber: item.number,
+  itemTitle: item.title,
+  itemUrl: item.html_url,
+  itemUpdatedAt: item.updated_at,
+  itemAuthorLogin: item.user?.login,
+}
+```
+
+**Done when:** A `github_issues_poll` trigger in a test fires `dispatch()` with the correct `WorkflowTrigger`. Existing `polling-scheduler.test.ts` GitLab cases still pass.
+
+---
+
+### Slice 5: Tests
+
+**Files:**
+- `tests/unit/github-poller.test.ts` (new)
+- `tests/unit/trigger-store.test.ts` (extend)
+- `tests/unit/polling-scheduler.test.ts` (extend)
+
+**`github-poller.test.ts` cases:**
+- Success: 2 issues returned from fake fetch
+- Empty: API returns empty array
+- HTTP 401: returns `http_error`
+- HTTP 500: returns `http_error`
+- Network error: returns `network_error`
+- Invalid JSON: returns `parse_error`
+- Non-array response: returns `parse_error`
+- Malformed items: skipped, valid items returned
+- `excludeAuthors` filter: bot-authored item excluded
+- `notLabels` filter: labeled item excluded
+- Rate limit skip: `X-RateLimit-Remaining=50` returns `ok([])` with log
+- PR `updated_at` filter: item older than `since` excluded
+- Issues URL construction: correct params including `since` and `labels`
+- PRs URL construction: no `since` param, sort by updated
+- Auth header: `Authorization: Bearer <token>`
+
+**Done when:** All new tests pass, all existing trigger-related tests pass.
+
+---
+
+### Slice 6: Exports and documentation
+
+**Files:**
+- `src/trigger/index.ts` -- export `GitHubPollingSource` and `PollingSource` if needed
+- `docs/design/github-polling-adapter-design-candidates.md` (already written)
+- `docs/design/github-polling-adapter-design-review-findings.md` (already written)
+
+**Done when:** Module exports are consistent. No breaking changes to existing exports.
+
+---
+
+## 8. Test Design
+
+**Framework:** Vitest (same as existing trigger tests)
+
+**Pattern:** Inject `fetchFn: FetchFn` as a `vi.fn()` fake returning controlled responses. Never use real HTTP.
+
+**Template:** Mirror `tests/unit/gitlab-poller.test.ts` structure exactly:
+- Helper functions: `makeSource()`, `makeIssue()`, `makePR()`, `makeFetch()`
+- Describe blocks per behavior group
+- Explicit `result.kind === 'ok'` / `result.kind === 'err'` narrowing before assertions
+
+**Coverage target:** All branches in both adapter functions. All filter logic (excludeAuthors, notLabels, updated_at).
+
+---
+
+## 9. Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| Self-loop from unconfigured `excludeAuthors` | Medium | HIGH | Mandatory warning in config comment; document in triggers.yml example |
+| Rate limit exhaustion on high-volume repos | Low | Medium | `X-RateLimit-Remaining < 100` skip + reset timestamp in log |
+| `github_issues_poll` catches open PRs accidentally | Low | Low | Document in adapter comment: "includes open PRs (they are also issues)" |
+| >100 PRs updated per poll interval silently missed | Low | Low | Document in `pollIntervalSeconds` comment |
+| `feat-polling-triggers` PR changes conflict | Low | Low | Branch this work on `feat-polling-triggers`; rebase after #404 merges |
+
+---
+
+## 10. PR Packaging Strategy
+
+**Single PR** on branch `feat/github-polling-adapter`, based on `feat-polling-triggers`.
+
+All 6 slices in one PR because:
+- The discriminated union type change and the adapter implementation are tightly coupled
+- Tests validate the full integration path
+- The PR is digestible in size (est. 400-600 lines new/changed)
+
+---
+
+## 11. Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|---|---|---|
+| 1 (types) | Make illegal states unrepresentable | Satisfied -- tagged union |
+| 1 (types) | Immutability by default | Satisfied -- all fields readonly |
+| 2 (trigger-store) | Validate at boundaries | Satisfied -- assembler validates all fields |
+| 2 (trigger-store) | Errors are data | Satisfied -- missing_field, invalid_field_value errors |
+| 3 (adapter) | Dependency injection | Satisfied -- fetchFn injectable |
+| 3 (adapter) | Errors are data | Satisfied -- Result<T,E> return |
+| 3 (adapter) | Determinism over cleverness | Satisfied -- exact string match for excludeAuthors |
+| 4 (scheduler) | Exhaustiveness everywhere | Satisfied -- switch on provider with no silent default |
+| 4 (scheduler) | Compose with small, pure functions | Satisfied -- split buildWorkflowTrigger |
+| 5 (tests) | Prefer fakes over mocks | Satisfied -- vi.fn() fake fetchFn |
+| 5 (tests) | Document why not what | Satisfied -- test case names describe behavior, not implementation |
+
+---
+
+## Plan Confidence
+
+- `planConfidenceBand`: High
+- `unresolvedUnknownCount`: 1 (whether `excludeAuthors` exact match is truly sufficient for the WorkTrain bot account naming convention -- acceptable for MVP)
+- `estimatedPRCount`: 1
+- `followUpTickets`: ["Add glob support to excludeAuthors", "Implement pagination for high-volume repos", "Add X-RateLimit-Reset-based backoff", "Auto-detect WorkTrain bot account login for default excludeAuthors"]