@exaudeus/workrail 3.46.0 → 3.47.0

package/docs/design/queue-label-support-implementation-plan.md

@@ -0,0 +1,158 @@
+# Implementation Plan: Label-Based Queue Filter for github_queue_poll
+
+## Problem Statement
+
+The `github_queue_poll` trigger supports `queueType: label` and `queueLabel: "worktrain:ready"` in `triggers.yml`, but these fields are silently ignored. The `GitHubQueueConfig` type supports `type: 'label'` but throws `not_implemented` at runtime. Label-based queue filtering lets WorkTrain pick up issues without a dedicated bot account -- any issue labeled `worktrain:ready` becomes a candidate.
+
+---
+
+## Acceptance Criteria
+
+1. `pollGitHubQueueIssues()` with `config.type === 'label'` and `config.queueLabel === 'worktrain:ready'` sends `GET /repos/:owner/:repo/issues?state=open&labels=worktrain%3Aready&per_page=100`
+2. `pollGitHubQueueIssues()` with `config.type === 'label'` and no `config.queueLabel` returns `err({ kind: 'not_implemented', ... })` (config validation error path)
+3. `pollGitHubQueueIssues()` with `config.type === 'assignee'` still works (regression)
+4. `loadQueueConfig()` with `type: 'label'` and no `queueLabel` field in config.json returns `err(...)` (not `ok`)
+5. `loadQueueConfig()` with `type: 'label'` and `queueLabel: 'worktrain:ready'` returns `ok(config)` with `config.queueLabel === 'worktrain:ready'`
+6. `trigger-store.ts` parses `queueType` and `queueLabel` from triggers.yml into `GitHubQueuePollingSource`
+7. `npm run build` succeeds (no TypeScript errors)
+8. `npx vitest run tests/unit/github-queue-poller.test.ts` -- all tests pass
+9. `npx vitest run` -- no regressions
+
+---
+
+## Non-Goals
+
+- Do not touch `src/mcp/`
+- Do not touch `polling-scheduler.ts`
+- Do not implement `mention` or `query` queue types
+- Do not refactor surrounding code
+- Do not remove the existing `name?` field from `GitHubQueueConfig`
+
+---
+
+## Philosophy-Driven Constraints
+
+- All boundary functions return `Result<T, E>` -- no throws
+- All new interface fields are `readonly`
+- Validation at load time (`loadQueueConfig`): err if `type==='label'` and `queueLabel` absent
+- Defensive else branch in `pollGitHubQueueIssues`: unknown types return `not_implemented`
+- `encodeURIComponent` / URLSearchParams for URL safety
+
+---
+
+## Invariants
+
+- I1: `pollGitHubQueueIssues` with `type='assignee'` and `config.user` sends `assignee=<user>` param (unchanged)
+- I2: `pollGitHubQueueIssues` with `type='label'` and `config.queueLabel` sends `labels=<encoded>` param
+- I3: `pollGitHubQueueIssues` with `type='label'` and no `config.queueLabel` returns `err({ kind: 'not_implemented' })`
+- I4: `pollGitHubQueueIssues` with any other type returns `err({ kind: 'not_implemented' })`
+- I5: `loadQueueConfig` with `type='label'` and no `queueLabel` key in config.json returns `err(string)`
+- I6: No throws at any boundary
+
+---
+
+## Selected Approach
+
+**Additive optional field + load-time validation + poller URL branch**
+
+Four changes:
+1. `GitHubQueueConfig` interface: add `readonly queueLabel?: string`
+2. `loadQueueConfig()`: parse `q['queueLabel']`, validate it when `type==='label'`
+3. `GitHubQueuePollingSource` (types.ts): add `readonly queueType?: string`, `readonly queueLabel?: string`
+4. `trigger-store.ts`: parse `queueType`/`queueLabel` in `ParsedTriggerRaw` + `setTriggerField()` + assembly block
+5. `pollGitHubQueueIssues()`: replace hard not_implemented guard with assignee/label/else branching
+
+Runner-up was discriminated union -- rejected due to scope constraint and unnecessary complexity for this bounded change.
+
+---
+
+## Vertical Slices
+
+### Slice 1: `github-queue-config.ts` -- add `queueLabel` field + validation
+**Files**: `src/trigger/github-queue-config.ts`
+**What**: Add `readonly queueLabel?: string` to `GitHubQueueConfig` interface. In `loadQueueConfig()`, parse `q['queueLabel']` and add validation: if `rawType === 'label'` and `!queueLabel`, return `err('config.queue.queueLabel is required when type is "label"')`. Build the return object with `queueLabel` when present.
+**Done when**: Interface has `queueLabel?`, validation fires correctly, `npm run build` clean.
+
+### Slice 2: `types.ts` -- extend `GitHubQueuePollingSource`
+**Files**: `src/trigger/types.ts`
+**What**: Add `readonly queueType?: string` and `readonly queueLabel?: string` to `GitHubQueuePollingSource`.
+**Done when**: Fields present in interface, build clean.
+
+### Slice 3: `trigger-store.ts` -- parse `queueType`/`queueLabel` from YAML
+**Files**: `src/trigger/trigger-store.ts`
+**What**: 
+- Add `queueType?: string` and `queueLabel?: string` to `ParsedTriggerRaw` interface
+- Handle them in `setTriggerField()` switch
+- In the `github_queue_poll` assembly block, read `raw.queueType` and `raw.queueLabel` and include them in the `GitHubQueuePollingSource` object
+**Done when**: `triggers.yml` `self-improvement` trigger parses correctly with these fields; build clean.
+
+### Slice 4: `github-queue-poller.ts` -- implement label branch
+**Files**: `src/trigger/adapters/github-queue-poller.ts`
+**What**: Replace the current `if (config.type !== 'assignee') return err(not_implemented)` guard with:
+```typescript
+if (config.type === 'assignee' && config.user) {
+  url.searchParams.set('assignee', config.user);
+} else if (config.type === 'label' && config.queueLabel) {
+  url.searchParams.set('labels', config.queueLabel);
+} else {
+  return err({ kind: 'not_implemented', message: `Queue type "${config.type}" is not yet implemented` });
+}
+```
+Remove the old `if (config.user)` block that was AFTER the guard.
+Update JSDoc to reflect both supported types.
+**Done when**: Function correctly handles both assignee and label, build clean.
+
+### Slice 5: Tests -- update + add new tests
+**Files**: `tests/unit/github-queue-poller.test.ts`
+**What**:
+- REPLACE existing test at line 126 (`returns not_implemented for non-assignee queue type`) -- this test currently expects not_implemented for `{type: 'label', name: 'my-label'}`. It MUST be replaced, not kept.
+- ADD: `type: 'label'` with `queueLabel: 'worktrain:ready'` -> fetches with `labels=worktrain%3Aready` param
+- ADD: `type: 'label'` without `queueLabel` -> returns err with kind not_implemented (or config validation path)
+- KEEP as regression: `type: 'assignee'` test at line 105 (already tests assignee param)
+- Update `makeConfig()` helper: `name?` field can stay but add examples with `queueLabel`
+**Done when**: `npx vitest run tests/unit/github-queue-poller.test.ts` all pass.
+
+---
+
+## Test Design
+
+| Test | Expected behavior | Assertion |
+|------|-------------------|-----------|
+| label type + queueLabel | fetches with `labels=` param | URL contains `labels=worktrain%3Aready` |
+| label type + no queueLabel | returns not_implemented | `result.error.kind === 'not_implemented'` |
+| assignee type + user (regression) | fetches with `assignee=` param | URL contains `assignee=bob` |
+
+Existing tests for network_error, http_error, rate_limit, field mapping, maturity, idempotency: unchanged.
+
+---
+
+## Risk Register
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Forgetting to replace test at line 126 | High | CI fails | Explicit: replace that test first |
+| `polling-scheduler.ts` guard still blocks end-to-end | Certain | Production feature blocked | Document in PR description as follow-up |
+| URL encoding of `:` in `worktrain:ready` | Low | Wrong API call | Use `url.searchParams.set()` which encodes automatically |
+
+---
+
+## PR Packaging Strategy
+
+Single PR: `feat/queue-label-support`
+Commit: `feat(trigger): implement label-based queue filter for github_queue_poll`
+
+PR description should note: the `polling-scheduler.ts` guard at line 393 still checks `queueConfig.type !== 'assignee'` and will need a follow-up update for end-to-end production use. This PR implements the foundational layer.
+
+---
+
+## Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|-------|-----------|--------|
+| 1 (config) | validate-at-boundaries | satisfied: err if type=label and queueLabel absent |
+| 1 (config) | immutability by default | satisfied: readonly field |
+| 2 (types) | explicit domain types | satisfied: typed fields not raw strings |
+| 3 (trigger-store) | validate-at-boundaries | satisfied: queueType parsed and stored |
+| 4 (poller) | Result types, no throws | satisfied: err() return, no throw |
+| 4 (poller) | exhaustiveness | tension: else branch catches unknowns but not exhaustive switch |
+| 5 (tests) | prefer fakes over mocks | satisfied: injectable fetchFn mock |

package/docs/ideas/backlog.md

@@ -6481,3 +6481,77 @@ All five top-priority autonomous pipeline items shipped:
 4. **Level 1 usage: run WorkTrain on its own backlog** -- Create `worktrain:ready` issues for the top 10 ready tasks, assign to `worktrain-etienneb`, observe one full queue → pipeline run. Collect data on misclassifications and weak PRs before designing the grooming loop.
 
 5. **`worktrain inbox --watch`** -- Close the notification loop. Outbox exists, just needs the polling implementation.
+
+---
+
+## WorkTrain identity model: act as the user, not as a bot (Apr 20, 2026)
+
+**Design decision:** WorkTrain acts as the configured user, not as a separate bot account.
+
+### Why bot accounts are the wrong default
+
+Most developers -- especially at companies -- cannot create separate bot GitHub accounts. Jira, GitLab, and other enterprise systems tie authentication to employee identity. Requiring a separate account creates friction that blocks adoption entirely.
+
+WorkTrain's attribution signal is the **work pattern**, not the identity:
+- Branch name: `worktrain/<sessionId>` -- immediately recognizable
+- PR body footer: "🤖 Automated by WorkTrain" + session ID + workflow name
+- Commit co-author: `Co-Authored-By: WorkTrain <worktrain@noreply>`
+
+Anyone reviewing a PR knows it was autonomous. The developer's name on the PR is not a lie -- they configured WorkTrain to do this work on their behalf.
+
+### Queue membership without a bot account
+
+Assignee-based opt-in only works with a dedicated bot account. Label-based opt-in works with any setup:
+- Apply `worktrain:ready` label to an issue → WorkTrain picks it up
+- The queue poll trigger uses `queueType: label` + `queueLabel: "worktrain:ready"`
+- No bot account, no special permissions, no friction
+
+`workOnAll: true` (future) processes any open issue -- also requires no bot account.
+
+### Token: use your own PAT
+
+`$GITHUB_TOKEN` (your personal token) or a fine-grained PAT scoped to the target repo. WorkTrain uses it for API calls; the commit identity (`git user.name`, `git user.email`) is set separately in the worktree and can be whatever you want.
+
+---
+
+## Jira + GitLab integration for WorkTrain (Apr 20, 2026)
+
+**Context:** Most enterprise developers use Jira for tickets and GitLab for code hosting. WorkTrain should work in this environment without requiring GitHub or a bot account.
+
+### What exists
+
+`gitlab_poll` trigger already exists -- polls GitLab MR list and dispatches sessions when new/updated MRs appear. WorkTrain can already do autonomous MR review on GitLab.
+
+### What's missing
+
+**`jira_poll` trigger:** Poll a Jira board/sprint/filter for issues in a specific status (e.g., "In Progress", "Ready for Dev") assigned to the configured user, and dispatch WorkTrain sessions for them. The developer labels Jira issues for WorkTrain the same way they'd assign to a teammate.
+
+Proposed `jira_poll` config:
+```yaml
+- id: jira-queue
+  provider: jira_poll
+  jiraBaseUrl: https://zillow.atlassian.net
+  token: $JIRA_API_TOKEN
+  project: ACEI
+  statusFilter: "Ready for Dev"
+  assigneeFilter: "$JIRA_USERNAME"
+  workspacePath: /path/to/repo
+  branchStrategy: worktree
+  autoCommit: true
+  autoOpenPR: true
+  agentConfig:
+    maxSessionMinutes: 90
+```
+
+**GitLab issue queue:** Same as `github_queue_poll` but for GitLab issues. Dispatch coding sessions for GitLab issues labeled `worktrain` or in a specific milestone.
+
+### Implementation notes
+
+- `jira_poll` follows the same `PollingSource` discriminated union pattern as `gitlab_poll` and `github_queue_poll`
+- Jira REST API v3: `GET /rest/api/3/search?jql=project=X+AND+status="Ready for Dev"+AND+assignee=currentUser()`
+- Token: Jira API token (not OAuth -- simpler for developer tools)
+- `jira_poll` should extract issue title + description as the goal, and the Jira issue URL as `upstreamSpecUrl` in `TaskCandidate`
+
+### Priority
+
+Medium. GitLab MR review already works. Jira issue queue is the next most impactful integration for enterprise users. Design alongside the label-based GitHub queue -- the patterns are identical, just different API shapes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.46.0",
+  "version": "3.47.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {

package/workflows/mr-review-workflow.agentic.v2.json

@@ -312,7 +312,7 @@
     {
       "id": "phase-6-final-handoff",
       "title": "Phase 6: Final Handoff",
-      "prompt": "Provide the final MR review handoff.\n\nInclude:\n- MR title and purpose\n- review mode used\n- final recommendation and confidence band\n- confidence assessment summary, including the most important reason confidence was capped if it was not High\n- counts of Critical / Major / Minor / Nit findings\n- top findings with rationale\n- strongest remaining areas of uncertainty, if any\n- summary of the coverage ledger, especially any still-uncertain domains\n- ready-to-post MR comments summary\n- any validation outcomes a human reviewer should see\n- review environment status:\n  - what review target/context sources were successfully used\n  - what important sources were missing or ambiguous\n  - boundary confidence and context confidence\n  - how those limits affected the review\n- path to the full human-facing review artifact (`reviewDocPath`) only if one was created\n\nRules:\n- the final recommendation assists a human reviewer; it does not replace them\n- if `reviewDocPath` exists, treat it as a human-facing companion artifact only\n- be explicit when missing PR/ticket/doc/boundary context limited confidence\n- do not post comments, approve, reject, or merge unless the user explicitly asks\n\nIMPORTANT: After writing your notes, emit a structured verdict via complete_step's artifacts[] parameter using EXACTLY this schema (no extra fields):\n{\n  \"kind\": \"wr.review_verdict\",\n  \"verdict\": \"clean\" | \"minor\" | \"blocking\",\n  \"confidence\": \"high\" | \"medium\" | \"low\",\n  \"findings\": [ { \"severity\": \"critical\" | \"major\" | \"minor\" | \"nit\", \"summary\": \"one-line description\" } ],\n  \"summary\": \"one-line overall verdict summary\"\n}\nFor a clean review with no findings, use findings: []. The verdict field maps to severity: clean = no blocking issues, minor = small issues only, blocking = critical or major issues found.",
+      "prompt": "Provide the final MR review handoff.\n\nInclude:\n- MR title and purpose\n- review mode used\n- final recommendation and confidence band\n- confidence assessment summary, including the most important reason confidence was capped if it was not High\n- counts of Critical / Major / Minor / Nit findings\n- top findings with rationale\n- strongest remaining areas of uncertainty, if any\n- summary of the coverage ledger, especially any still-uncertain domains\n- ready-to-post MR comments summary\n- any validation outcomes a human reviewer should see\n- review environment status:\n  - what review target/context sources were successfully used\n  - what important sources were missing or ambiguous\n  - boundary confidence and context confidence\n  - how those limits affected the review\n- path to the full human-facing review artifact (`reviewDocPath`) only if one was created\n\nRules:\n- the final recommendation assists a human reviewer; it does not replace them\n- if `reviewDocPath` exists, treat it as a human-facing companion artifact only\n- be explicit when missing PR/ticket/doc/boundary context limited confidence\n- do not post comments, approve, reject, or merge unless the user explicitly asks\n\nIMPORTANT: After writing your notes, emit a structured verdict via complete_step's artifacts[] parameter using EXACTLY this schema (no extra fields):\n{\n  \"kind\": \"wr.review_verdict\",\n  \"verdict\": \"clean\" | \"minor\" | \"blocking\",\n  \"confidence\": \"high\" | \"medium\" | \"low\",\n  \"findings\": [ { \"severity\": \"critical\" | \"major\" | \"minor\" | \"nit\", \"summary\": \"one-line description\", \"findingCategory\": \"correctness\" | \"security\" | \"architecture\" | \"ux\" | \"performance\" | \"testing\" | \"style\" } ],\n  \"summary\": \"one-line overall verdict summary\"\n}\nFor a clean review with no findings, use findings: []. The verdict field maps to severity: clean = no blocking issues, minor = small issues only, blocking = critical or major issues found. For findingCategory use: correctness = wrong behavior/logic errors, security = auth/authz issues/injection/data exposure, architecture = wrong abstraction/tight coupling/invariant violations, ux = usability/accessibility/interaction design, performance = inefficiency/N+1/blocking operations, testing = missing tests/wrong test approach, style = naming/formatting/conventions.",
       "outputContract": {
         "contractRef": "wr.contracts.review_verdict",
         "required": false