@exaudeus/workrail 3.32.0 → 3.34.0

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"]

package/docs/design/implementation_plan.md

@@ -0,0 +1,192 @@
+# Implementation Plan: WorkTrain System Prompt Preamble + report_issue Tool
+
+## Problem Statement
+
+The WorkTrain daemon's system prompt preamble is thin (15 lines) and relies on the soul file for behavioral guidance. This leaves unattended agents without explicit direction on self-directed reasoning, the oracle hierarchy, or what to do when things go wrong. Additionally, there is no structured way for agents to record issues/errors for a future auto-fix coordinator -- failures either go unrecorded or end up buried in step notes.
+
+---
+
+## Acceptance Criteria
+
+1. `buildSystemPrompt()` output contains a richer preamble (~55 lines) that:
+   - Opens with "You are WorkRail Auto, an autonomous agent..." (existing test assertion preserved)
+   - Includes `## Your tools` section listing all 5 tools (existing test assertion)
+   - Includes `## Execution contract` section (existing test assertion)
+   - Adds `## What you are`, `## Your oracle`, `## Self-directed reasoning`, `## The workflow is the contract`, `## Silent failure is the worst outcome`, `## Tools are your hands not your voice`, `## You don't have a user` sections
+   - All existing `workflow-runner-system-prompt.test.ts` tests pass without modification
+
+2. `makeReportIssueTool(sessionId, emitter?, issuesDirOverride?)` is exported from `workflow-runner.ts`:
+   - Tool name: `report_issue`
+   - Input schema accepts: `kind` (5-value literal enum), `severity` (4-value literal enum), `summary` (string, required), `context` (string, optional), `toolName` (string, optional), `command` (string, optional), `suggestedFix` (string, optional), `continueToken` (string, optional)
+   - `execute()` appends one JSON line to `~/.workrail/issues/<sessionId>.jsonl` (or `issuesDirOverride/<sessionId>.jsonl` in tests) -- fire-and-forget (void+catch)
+   - `execute()` emits a `DaemonEventEmitter` event with `kind: 'issue_reported'`
+   - For non-fatal severity: returns `"Issue recorded (severity=<severity>). Continue with your work unless this is fatal."`
+   - For fatal severity: returns `"FATAL issue recorded. Call continue_workflow with notes explaining the blocker, then the session will end."`
+   - Wired into `runWorkflow()` tools array
+
+3. `IssueReportedEvent` is added to `DaemonEvent` union in `daemon-events.ts`:
+   - `kind: 'issue_reported'`, `sessionId: string`, `issueKind` (5-value literal union), `severity` (4-value literal union), `summary: string`, `continueToken?: string`
+
+4. `npm run build` succeeds (no TS errors)
+5. `npx vitest run` passes (all existing tests + new tests)
+
+---
+
+## Non-Goals
+
+- No auto-fix coordinator implementation
+- No IssueStore class (YAGNI -- extract when coordinator needs it)
+- No changes to `soul-template.ts`, `triggers.yml`, or `src/v2/`
+- No changes to the soul file template/default
+- No changes to AgentLoop behavior (fatal severity does not abort the loop)
+- No async changes to `buildSystemPrompt()` (must remain synchronous and pure)
+
+---
+
+## Philosophy-Driven Constraints
+
+- `buildSystemPrompt()` must remain a pure, synchronous function (no I/O, no side effects)
+- All `DaemonEvent` variants must use `readonly` fields only
+- `IssueReportedEvent.issueKind` and `.severity` must be literal union types (not `string`)
+- JSONL write must be fire-and-forget: `void appendIssueAsync().catch(() => {})`
+- `mkdir({ recursive: true })` before every appendFile (handles missing dir silently)
+- `issuesDirOverride` parameter for test isolation (mirrors DaemonEventEmitter constructor)
+
+---
+
+## Invariants
+
+1. `buildSystemPrompt()` is pure and synchronous -- verified by existing tests calling it directly
+2. `'You are WorkRail Auto'` is present in `buildSystemPrompt()` output -- verified by test L29
+3. `'## Your tools'` is present in `buildSystemPrompt()` output -- verified by test L30
+4. `'## Execution contract'` is present in `buildSystemPrompt()` output -- verified by test L32
+5. All `DaemonEvent` variants use `readonly` fields -- verified by TS compiler
+6. `DaemonEvent` union is exhaustive -- TS compiler enforces at every switch site
+7. `report_issue.execute()` never throws -- returns `AgentToolResult` always
+8. JSONL write never blocks `execute()` return -- `void` Promise
+
+---
+
+## Selected Approach + Rationale
+
+**Part 1:** Module-private `BASE_SYSTEM_PROMPT` string constant defined above `buildSystemPrompt()`. The function uses it as the start of the lines array. Rationale: named constant is readable as a document; testable via `buildSystemPrompt()` output; follows `soul-template.ts` precedent for stable-content constants.
+
+**Part 2:** `makeReportIssueTool(sessionId, emitter?, issuesDirOverride?)` inline tool factory following the exact shape of `makeReadTool`/`makeWriteTool`. Private `appendIssueAsync()` helper for JSONL write. `issuesDirOverride` for test isolation (hybrid of inline factory + runner-up's dirOverride). Rationale: YAGNI -- no IssueStore class until coordinator exists; hybrid resolves testability without over-engineering.
+
+**Runner-up:** IssueStore class (Candidate B). Lost to YAGNI -- one caller, no coordinator yet.
+
+---
+
+## Vertical Slices
+
+### Slice 1: Create feature branch
+- Create `feat/worktrain-system-prompt-and-report-issue` from current main
+- Verify clean state
+
+### Slice 2: Add IssueReportedEvent to daemon-events.ts
+- Add `IssueReportedEvent` interface
+- Add to `DaemonEvent` union
+- Verify TS compiles
+
+### Slice 3: Replace buildSystemPrompt() preamble
+- Define `BASE_SYSTEM_PROMPT` constant above `buildSystemPrompt()`
+- Replace lines 1087-1108 to use the constant
+- Verify all existing system-prompt tests pass
+
+### Slice 4: Implement makeReportIssueTool
+- Add private `appendIssueAsync()` helper
+- Add `makeReportIssueTool()` factory
+- Wire into `runWorkflow()` tools array
+
+### Slice 5: Tests
+- Add tests for `makeReportIssueTool` -- verify JSONL write with temp dir, verify event emitted, verify return strings, verify fatal vs non-fatal
+- Verify all existing tests still pass
+
+### Slice 6: Build + full test run
+- `npm run build` -- zero errors
+- `npx vitest run` -- all pass
+
+### Slice 7: PR
+- Commit with conventional commit message
+- Open PR to main
+
+---
+
+## Test Design
+
+### Existing tests (must pass unchanged)
+- `tests/unit/workflow-runner-system-prompt.test.ts` -- all 11 tests
+- `tests/unit/daemon-events.test.ts` -- all existing tests
+
+### New tests to add
+File: `tests/unit/workflow-runner-report-issue.test.ts`
+
+Test cases:
+1. `makeReportIssueTool` -- returns correct tool name and description
+2. `execute()` with non-fatal severity -- returns confirmation string with severity
+3. `execute()` with fatal severity -- returns FATAL message
+4. `execute()` -- writes JSON line to issuesDirOverride/<sessionId>.jsonl
+5. `execute()` -- written JSON contains kind, severity, summary, ts, sessionId
+6. `execute()` -- creates dir if it doesn't exist (mkdir recursive)
+7. `execute()` -- emits `issue_reported` event via emitter
+8. `execute()` -- optional fields (context, toolName, command, suggestedFix, continueToken) present in JSON when provided
+9. `execute()` -- does not throw when write fails (fire-and-forget)
+
+---
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| BASE_SYSTEM_PROMPT missing required test strings | Low | High (CI break) | Include `'You are WorkRail Auto'`, `'## Your tools'`, `'## Execution contract'` explicitly; tests catch immediately |
+| IssueReportedEvent `issueKind` vs tool input `kind` confusion | Low | Medium (runtime behavior ok, TS shape wrong) | Use `issueKind` in event interface; keep `kind` in input schema |
+| Silent JSONL write failure not caught in tests | Low | Low (fire-and-forget is intentional) | issuesDirOverride isolates write path; test case #9 verifies no throw |
+| Agent ignores fatal severity | Medium | Medium (tokens wasted) | Out of scope; coordinator detects post-hoc |
+
+---
+
+## PR Packaging Strategy
+
+Single PR: `feat/worktrain-system-prompt-and-report-issue`
+- All 3 files changed: `src/daemon/workflow-runner.ts`, `src/daemon/daemon-events.ts`, `tests/unit/workflow-runner-report-issue.test.ts`
+- Commit message: `feat(console): richer daemon system prompt and report_issue tool`
+
+Wait -- scope is `daemon`, not `console`. Correct commit message:
+`feat(mcp): richer daemon system prompt and report_issue tool for auto-fix coordinator`
+
+Actually these are daemon changes. The allowed scopes from CLAUDE.md are: `console`, `mcp`, `workflows`, `engine`, `schema`, `docs`. The daemon lives under `mcp` in this codebase (daemon is part of the WorkRail server). Use scope `mcp`.
+
+---
+
+## Philosophy Alignment Per Slice
+
+### Slice 2 (daemon-events.ts)
+- Exhaustiveness everywhere -> satisfied (new union variant, TS enforces handling)
+- Make illegal states unrepresentable -> satisfied (literal unions for issueKind/severity)
+- Immutability by default -> satisfied (readonly fields)
+
+### Slice 3 (BASE_SYSTEM_PROMPT)
+- Functional core, imperative shell -> satisfied (buildSystemPrompt remains pure)
+- Immutability by default -> satisfied (const)
+- Document why not what -> satisfied (JSDoc on constant)
+- YAGNI with discipline -> satisfied (no speculative additions)
+
+### Slice 4 (makeReportIssueTool)
+- Observability as a constraint -> satisfied (fire-and-forget, never blocks)
+- Errors are data -> satisfied (execute() returns AgentToolResult, never throws)
+- Prefer fakes over mocks -> satisfied (issuesDirOverride for tests)
+- YAGNI with discipline -> satisfied (no IssueStore class)
+- Exhaustiveness everywhere -> satisfied (return value handles all severity levels)
+
+### Slice 5 (tests)
+- Prefer fakes over mocks -> satisfied (temp dir, no fs mocking)
+- Determinism -> satisfied (all test writes go to unique temp dirs)
+
+---
+
+## Summary
+
+- `estimatedPRCount`: 1
+- `planConfidenceBand`: High
+- `unresolvedUnknownCount`: 0
+- `followUpTickets`: Extract IssueStore class when auto-fix coordinator is built

package/docs/design/workflow-id-validation-at-startup.md

@@ -0,0 +1,146 @@
+# Design: Workflow ID Validation at Daemon Startup
+
+**Status:** Decision made -- implement Candidate A  
+**Date:** 2026-04-16  
+**Context:** Backlog item "Workflow ID validation at startup" (Tier 1, groomed Apr 18)
+
+---
+
+## Problem Understanding
+
+### The Bug
+
+A user writes `workflowId: coding-task-workflow-agentic.lean.v2` (filename without extension) instead of `coding-task-workflow-agentic` (the actual workflow ID). The daemon starts fine, accepts webhooks, but every dispatch silently fails with `workflow_not_found`. The error only surfaces in logs, not at startup. The operator has no way to know their trigger is broken until they watch logs during an actual webhook event.
+
+### Core Tensions
+
+1. **Testability vs. production simplicity** -- `ctx.workflowService.getWorkflowById` is available in production but tests use `FAKE_CTX = {} as V2ToolContext` where `workflowService` is `undefined`. Requires an injectable function approach, not direct ctx access.
+2. **Warn+skip consistency vs. fail-fast** -- `loadTriggerConfig` already chose warn+skip for invalid triggers. A hard-fail here would create two conflicting behaviors in the same startup path.
+3. **Where to wire the lookup** -- `StartTriggerListenerOptions` injectable (matches existing `runWorkflowFn` pattern) vs. direct `ctx` access.
+
+### Likely Seam
+
+`startTriggerListener` in `src/trigger/trigger-listener.ts`, after `buildTriggerIndex()` returns ok (~line 235), before `new TriggerRouter(...)`. This is the correct seam -- triggers are loaded and indexed, but no webhooks can arrive yet.
+
+### What Makes This Hard
+
+- `FAKE_CTX = {} as V2ToolContext` in tests -- direct `ctx.workflowService` use breaks existing test infrastructure without any compile-time warning.
+- Need to decide what happens when `getWorkflowByIdFn` is not provided (backward compat: skip validation entirely).
+- Workflows are static YAML files -- if not found at startup, they will never be found at dispatch time either. No "not found now, maybe later" case exists.
+
+---
+
+## Philosophy Constraints
+
+**Sources:**
+- `/Users/etienneb/CLAUDE.md`: "Dependency injection for boundaries -- inject external effects (I/O, clocks, randomness) to keep core logic testable"
+- `/Users/etienneb/CLAUDE.md`: "Validate at boundaries, trust inside -- do input validation at system edges"
+- Repo pattern: `runWorkflowFn?: RunWorkflowFn` in `StartTriggerListenerOptions` -- exact injectable pattern to follow
+- Repo pattern: `loadTriggerConfig` warn+skip -- policy to remain consistent with
+
+**No conflicts.** All sources agree on: DI injectable for testability, warn+skip policy, validate at the startup boundary.
+
+---
+
+## Impact Surface
+
+- **`src/trigger/trigger-listener.ts`** -- primary change. New validation loop and new `StartTriggerListenerOptions` field.
+- **`tests/unit/trigger-router.test.ts`** -- add new test cases. Existing tests unaffected (they don't provide `getWorkflowByIdFn`, so validation is skipped -- same behavior as today).
+- **`src/trigger/trigger-router.ts`** -- no change. Router already handles `workflow_not_found` at dispatch; this is an earlier defense layer.
+- **`src/trigger/trigger-store.ts`** -- no change. YAML parsing is separate from workflow ID resolution.
+- **`src/trigger/types.ts`** -- no change. `TriggerDefinition` shape unchanged.
+
+---
+
+## Candidates
+
+### Candidate A -- Injectable function on StartTriggerListenerOptions (RECOMMENDED)
+
+**Summary:** Add `getWorkflowByIdFn?: (id: string) => Promise<boolean>` to `StartTriggerListenerOptions`. Production path defaults to `(id) => ctx.workflowService.getWorkflowById(id).then(w => w !== null)`. When not provided, validation is skipped (backward compat for existing tests).
+
+**Tensions resolved:** Testability (tests inject stub), warn+skip consistency, DI principle.  
+**Tensions accepted:** Slight verbosity (new option field). Validation silently skipped if fn not provided (intentional).
+
+**Boundary:** `startTriggerListener`, after `buildTriggerIndex()` returns ok.  
+**Why this boundary:** Single assembly point before the router accepts any traffic. Earlier (store layer) would require making `loadTriggerConfig` async. Later (dispatch time) is too late -- that's the bug we're fixing.
+
+**Failure mode:** Existing tests that don't inject `getWorkflowByIdFn` silently skip validation. This is intentional backward compat, not a latent bug -- they still test all other startup behavior.
+
+**Repo pattern:** Exact match to `runWorkflowFn?: RunWorkflowFn` in the same `StartTriggerListenerOptions` interface.
+
+**Gains:** Full testability, no changes to existing tests, clean DI seam, consistent with all philosophy principles.  
+**Losses:** Caller must inject the fn to get validation. If someone creates a new caller of `startTriggerListener` without providing it, they get no validation. (Low risk: only one production caller.)
+
+**Scope judgment:** Best-fit. Changes only `trigger-listener.ts` and adds tests. No interface changes to store or router.
+
+**Philosophy fit:** Honors "Dependency injection for boundaries", "Validate at boundaries, trust inside". No conflicts.
+
+---
+
+### Candidate B -- Use ctx.workflowService directly with null guard
+
+**Summary:** Call `ctx.workflowService?.getWorkflowById(id)` directly in the validation loop, skipping the whole loop if `ctx.workflowService` is undefined.
+
+**Tensions resolved:** Production simplicity (no new option field).  
+**Tensions accepted:** Testability gap -- the warn+skip behavior can't be tested without constructing a real `workflowService` in `ctx`.
+
+**Failure mode:** New validation behavior is untestable with the existing `FAKE_CTX` test infrastructure.
+
+**Repo pattern:** Departs from `runWorkflowFn` injectable pattern. Conflicts with DI principle.
+
+**Scope judgment:** Best-fit for production behavior, too narrow for test coverage.
+
+**Philosophy fit:** Conflicts with "Dependency injection for boundaries".
+
+---
+
+### Candidate C -- Validate inside loadTriggerConfig (store layer)
+
+**Summary:** Add `workflowResolver?: (id: string) => Promise<boolean>` to `loadTriggerConfig`, filtering unknown workflowId triggers at parse time.
+
+**Tensions resolved:** Centralizes all trigger validation.  
+**Tensions accepted:** `trigger-store.ts` is a pure synchronous YAML parser; making it async for the resolver breaks its pure/impure boundary and all existing sync call sites.
+
+**Failure mode:** Breaks `loadTriggerConfig`'s synchronous interface contract. All existing callers would need updating.
+
+**Repo pattern:** Departs from the pure-sync design of `trigger-store.ts`.
+
+**Scope judgment:** Too broad -- adds async I/O to a pure parsing module with no justification beyond this feature.
+
+**Philosophy fit:** Conflicts with "Compose with small, pure functions".
+
+---
+
+## Comparison and Recommendation
+
+| Tension | A (Injectable) | B (ctx direct) | C (store layer) |
+|---------|---------------|----------------|-----------------|
+| Testability | Wins | Loses | N/A |
+| Warn+skip consistency | Wins | Wins | Breaks pure boundary |
+| DI principle | Honors | Conflicts | Conflicts |
+| Repo pattern fit | Exact match | Departs | Departs |
+| Reversibility | Easy | Easy | Hard |
+
+**Recommendation: Candidate A.** It resolves all tensions, is a direct repo-pattern match, requires minimal code change, and leaves all existing tests unchanged.
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument:** "Why add a new option when `ctx.workflowService` is already there? That's extra API surface for a one-time startup check." -- Response: `FAKE_CTX = {} as V2ToolContext` (line 33, `trigger-router.test.ts`) means `ctx.workflowService` is `undefined` at test runtime. Without the injectable, the new validation behavior is untestable. Fixing a silent-failure bug without being able to test it is unacceptable.
+
+**Narrower option that lost:** Candidate B (ctx direct with null guard). Loses because new behavior is untestable.
+
+**Broader option that would need evidence:** Candidate C (store layer) would be justified if multiple callers of `loadTriggerConfig` needed workflow ID validation -- but there is only one production caller. The scope increase is not warranted.
+
+**Invalidating assumption:** If `FAKE_CTX` were replaced by a real mock with a `workflowService`, Candidate B would be equally valid. But that's a larger test infrastructure change that's out of scope.
+
+---
+
+## Open Questions for the Main Agent
+
+None. All design decisions are resolved. Implementation is straightforward:
+1. Add `getWorkflowByIdFn?: (id: string) => Promise<boolean>` to `StartTriggerListenerOptions`
+2. After `buildTriggerIndex()` returns ok, if `getWorkflowByIdFn` is provided, iterate `triggerIndex`, call fn for each `workflowId`, warn and delete unknowns
+3. Production default (when fn not provided): use `ctx.workflowService.getWorkflowById(id).then(w => w !== null)`
+4. Add test cases for: warn+skip on unknown workflowId, valid workflowId passes through, fn not provided skips validation