@exaudeus/workrail 3.44.0 → 3.46.0

package/docs/design/design-candidates-stuck-escalation.md

@@ -0,0 +1,183 @@
+# Design Candidates: WorkTrain Stuck-Escalation
+
+*Generated: 2026-04-19 | Pitch: .workrail/current-pitch.md*
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Stuck vs timeout conflation**: When `repeated_tool_call` fires, the session
+   currently runs until wall-clock or max-turns timeout. The result is
+   `_tag: 'timeout'`, which is indistinguishable from a legitimate slow session.
+   Automated routing requires a distinct discriminant.
+
+2. **Abort vs notify-only independence**: Outbox notification and `agent.abort()`
+   are two separate effects. `notify_only` policy suppresses the abort but must
+   not suppress the outbox write. These effects must not be coupled.
+
+3. **ChildWorkflowRunResult atomic update**: The `as ChildWorkflowRunResult` cast
+   at line 2172 in `makeSpawnAgentTool` suppresses any compile-time error from a
+   missing union update. Only the `assertNever(childResult)` at line 2212 catches
+   the omission -- at runtime, crashing the parent session.
+
+4. **no_progress false-positive risk**: The no_progress heuristic fires on
+   legitimate research workflows that spend many turns reading before advancing.
+   It must be opt-in (default: false) to avoid breaking existing sessions.
+
+### Likely Seam
+
+The `turn_end` subscriber in `runWorkflow()` is the correct location. All
+required state (lastNToolCalls, stepAdvanceCount, timeoutReason, issueSummaries)
+is available there as closure variables. Detection fires at the right moment
+(after each turn, synchronously before next step injection).
+
+### What Makes This Hard
+
+- The `as ChildWorkflowRunResult` cast is a type-safety trap: it silences
+  TypeScript while leaving a runtime crash. Only careful reading of the pitch
+  reveals the issue.
+- `buildOutcome()` in notification-service.ts has return type
+  `NotificationPayload['outcome']`. Adding 'stuck' to WorkflowRunResult causes
+  a compile error there unless the outcome union is also widened.
+
+---
+
+## Philosophy Constraints
+
+From CLAUDE.md:
+
+- **Make illegal states unrepresentable**: the stuck discriminant prevents
+  conflating stuck with timeout at the type level.
+- **Exhaustiveness everywhere**: assertNever guards in trigger-router and
+  makeSpawnAgentTool enforce this -- adding stuck arm is required.
+- **Errors are data**: WorkflowRunResult is a Result type; WorkflowRunStuck is
+  a new variant, not an exception.
+- **Type safety as first line of defense**: ChildWorkflowRunResult update in
+  same commit restores the compile-time invariant that the cast broke.
+- **Fire-and-forget for side effects**: outbox write uses void + catch, same
+  as DaemonEventEmitter and issue recording.
+
+No conflicts between stated philosophy and repo patterns.
+
+---
+
+## Impact Surface
+
+Paths that must stay consistent when WorkflowRunResult gains a new variant:
+
+1. `makeSpawnAgentTool` -- `assertNever(childResult)` at line 2212; requires
+   ChildWorkflowRunResult update and a new `stuck` arm in the result mapping.
+2. `trigger-router.ts` `route()` -- exhaustive if-else chain ending in
+   `assertNever(result)` at line ~689.
+3. `trigger-router.ts` `dispatch()` -- same exhaustive chain at line ~770.
+4. `notification-service.ts` `buildNotificationBody()` -- exhaustive switch.
+5. `notification-service.ts` `buildDetail()` -- exhaustive switch.
+6. `notification-service.ts` `buildOutcome()` -- return type
+   `NotificationPayload['outcome']`; 'stuck' must be added to that union.
+7. `NotificationPayload.outcome` union -- currently
+   `'success' | 'error' | 'timeout' | 'delivery_failed'`; must add `'stuck'`.
+
+---
+
+## Candidates
+
+### Candidate A: New `_tag: 'stuck'` discriminated union variant (SELECTED)
+
+**Summary**: Add `WorkflowRunStuck` interface with `_tag: 'stuck'`, wire abort
+in turn_end subscriber after Signal 1 and Signal 2 emitter calls, return stuck
+result before timeout check, update both `WorkflowRunResult` and
+`ChildWorkflowRunResult` unions atomically, add `writeStuckOutboxEntry` helper.
+
+**Tensions resolved**:
+- Stuck/timeout conflation: separate discriminant, separate return path.
+- Abort/notify independence: outbox write fires before the abort gate check.
+- ChildWorkflowRunResult crash: atomic update with assertNever arm added.
+- no_progress false-positive: gated by `noProgressAbortEnabled: false` default.
+
+**Boundary solved at**: `turn_end` subscriber (detection + abort), result
+construction (return), 4 files for propagation to callers.
+
+**Why best-fit boundary**: The turn_end subscriber is the only location with
+access to all required state. The result construction is the canonical output
+boundary for runWorkflow(). Propagation to callers follows the existing
+WorkflowRunResult variant fan-out pattern.
+
+**Failure mode**: Forgetting to update `NotificationPayload.outcome` union --
+caught by `npm run build` (TypeScript compile error in `buildOutcome()`).
+
+**Repo-pattern relationship**: Mirrors `timeoutReason` flag pattern exactly.
+Mirrors `WorkflowRunTimeout` interface field shape. Follows assertNever guard
+pattern already established in trigger-router and makeSpawnAgentTool.
+
+**Gains**: Distinct routing for stuck sessions, type-safe callers, clean
+separation of abort and notification effects.
+
+**Losses**: One more variant in the union (minor cognitive load increase).
+
+**Scope judgment**: Best-fit. 4 files, mechanical wiring, all design resolved.
+
+**Philosophy fit**: Honors all relevant CLAUDE.md principles. No conflicts.
+
+---
+
+### Candidate B: Extend `WorkflowRunTimeout.reason` with stuck sub-values
+
+**Summary**: Add `'stuck_repeated_tool_call' | 'stuck_no_progress'` to
+`WorkflowRunTimeout.reason` -- reuse the timeout discriminant.
+
+**Tensions resolved**: None of the core ones. Stuck and timeout still share
+`_tag: 'timeout'`, requiring callers to inspect reason to distinguish them.
+
+**Failure mode**: Violates make-illegal-states-unrepresentable. Callers using
+`result._tag === 'timeout'` would silently handle stuck sessions as timeouts.
+
+**Repo-pattern relationship**: Departs from the exhaustiveness-everywhere
+pattern. The assertNever guard pattern exists precisely to avoid this.
+
+**Scope judgment**: Too narrow -- preserves the routing problem this pitch
+exists to solve.
+
+**Rejected because**: Violates philosophy, does not resolve the core tension,
+and the pitch explicitly rejects conflating stuck with timeout.
+
+---
+
+## Comparison and Recommendation
+
+Candidate A is the only viable candidate. All analysis converges.
+
+The core recommendation is to implement Candidate A exactly as specified in
+`.workrail/current-pitch.md`, with one addition not noted in the pitch:
+update `NotificationPayload.outcome` union to include `'stuck'` (required for
+`buildOutcome()` to compile).
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument**: Adding a 5th variant to WorkflowRunResult
+increases cognitive load for callers. Counter: assertNever guards make missing
+cases compile errors, which is the correct safeguard. The complexity cost is
+paid once (at implementation) and enforced automatically.
+
+**Narrower option that lost**: Update only WorkflowRunResult, skip
+ChildWorkflowRunResult. Lost because: runtime crash in makeSpawnAgentTool
+when a child hits stuck-abort. The cast at line 2172 provides no protection.
+
+**Broader option not justified**: Adding `onStuck:` hook to TriggerDefinition.
+Explicitly deferred per pitch No-Gos. Would require trigger-store.ts parser
+changes -- outside the 4-file scope.
+
+**Pivot condition**: If `assertNever(childResult)` were removed in favor of a
+logged fallback, ChildWorkflowRunResult update would be less critical. It is
+not removed, so the atomic update is required.
+
+---
+
+## Open Questions for the Main Agent
+
+None. All design decisions are resolved in the pitch. The only implementation
+detail requiring attention is the `NotificationPayload.outcome` union widening
+(add 'stuck') -- verify this compiles before finalizing.

package/docs/design/design-review-findings-stuck-escalation.md

@@ -0,0 +1,93 @@
+# Design Review Findings: WorkTrain Stuck-Escalation
+
+*Generated: 2026-04-19 | Pitch: .workrail/current-pitch.md*
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Status | Condition for Failure |
+|----------|--------|-----------------------|
+| One more union variant in WorkflowRunResult | Acceptable | All callers use assertNever guards -- compile error enforces handling |
+| ChildWorkflowRunResult atomic update relies on discipline | Managed | Fails only if commit is split; mitigated by single-PR implementation and compile-time test |
+| NotificationPayload.outcome union widening (gap, not tradeoff) | Resolved | Add 'stuck' to outcome union; caught by npm run build |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Severity | Design Handling | Missing Mitigation |
+|--------------|----------|-----------------|--------------------|
+| ChildWorkflowRunResult not updated | High | Atomic commit, compile-time assignability test | None beyond discipline |
+| stuckReason / timeoutReason race | Low | First-writer-wins guard; max_turns early return prevents race | None needed |
+| writeStuckOutboxEntry fails | Low | Fire-and-forget, console.warn on error | None -- intentional |
+| no_progress fires on research workflow | Low | noProgressAbortEnabled defaults to false | None needed |
+| NotificationPayload.outcome compile error | Medium | Add 'stuck' to union | None -- caught at build |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+- **Candidate B** (extend WorkflowRunTimeout.reason): No elements worth borrowing.
+  Does not resolve the core routing tension.
+- **Skip ChildWorkflowRunResult**: Not acceptable -- runtime crash in parent session.
+- **Skip sessionStartMs**: Not recommended -- pitch explicitly adds it for Signal 5 follow-up
+  to avoid future restructuring.
+- **Inline outbox write**: Works but reduces turn_end subscriber readability. Not worth it.
+
+No hybrid opportunities identified.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|-----------|--------|
+| Make illegal states unrepresentable | Satisfied |
+| Exhaustiveness everywhere | Satisfied |
+| Errors are data | Satisfied |
+| Immutability by default | Satisfied |
+| Type safety as first line of defense | Under tension (pre-existing cast; improved but not fully resolved) |
+| Fire-and-forget for side effects | Satisfied |
+
+---
+
+## Findings
+
+### Yellow: NotificationPayload.outcome union widening not specified in pitch
+
+The pitch states 'buildOutcome() returns result._tag directly -- no change needed'.
+However, the return type annotation `NotificationPayload['outcome']` will cause a
+TypeScript compile error when 'stuck' is added to WorkflowRunResult but not to the
+outcome union. **Resolution**: add `'stuck'` to `NotificationPayload.outcome` union
+in notification-service.ts. This is a mechanical fix, not a design change.
+
+### Yellow: Pre-existing `as ChildWorkflowRunResult` cast at line 2172
+
+The cast suppresses TypeScript's compile-time check that would otherwise catch a
+missing ChildWorkflowRunResult update. This PR updates the union and adds a
+compile-time assignability test to partially compensate. Removing the cast is
+out of scope. **Residual concern**: future union additions must be caught by the
+test rather than the compiler.
+
+---
+
+## Recommended Revisions
+
+1. Add `'stuck'` to `NotificationPayload.outcome` union (not in pitch, required for compile).
+2. Add compile-time assignability test for `ChildWorkflowRunResult` in the test file.
+3. Document the `as ChildWorkflowRunResult` cast issue in a code comment at line 2172
+   (or verify existing comment is sufficient).
+
+---
+
+## Residual Concerns
+
+- The `as ChildWorkflowRunResult` cast remains. Future contributors adding a new
+  WorkflowRunResult variant may forget to update ChildWorkflowRunResult. The
+  compile-time test in the stuck-escalation test file partially mitigates this,
+  but only for the stuck variant. A broader structural fix (removing the cast)
+  is a follow-up.
+- Webhook consumers reading `outcome: 'stuck'` must handle the new value.
+  This is a new feature, not a breaking change, but operators consuming the
+  webhook should be aware.

package/docs/design/implementation-plan-stuck-escalation.md

@@ -0,0 +1,172 @@
+# Implementation Plan: WorkTrain Stuck-Escalation
+
+*2026-04-19 | Pitch: .workrail/current-pitch.md*
+
+---
+
+## 1. Problem Statement
+
+When a WorkTrain daemon session enters a `repeated_tool_call` loop, the session
+currently burns turns until wall-clock or max-turn timeout. The result is
+`_tag: 'timeout'`, indistinguishable from a legitimate slow session. Automated
+routing is impossible without string-parsing.
+
+---
+
+## 2. Acceptance Criteria
+
+1. `WorkflowRunStuck` interface exported from `workflow-runner.ts` with fields:
+   `_tag: 'stuck'`, `workflowId`, `reason`, `message`, `stopReason`, `issueSummaries?`
+2. `WorkflowRunResult` union includes `WorkflowRunStuck`.
+3. `ChildWorkflowRunResult` union includes `WorkflowRunStuck` (SAME COMMIT as #2).
+4. `WorkflowTrigger.agentConfig` has `stuckAbortPolicy?` and `noProgressAbortEnabled?`.
+5. `TriggerDefinition.agentConfig` has the same two fields.
+6. When `repeated_tool_call` fires and `stuckAbortPolicy !== 'notify_only'`:
+   outbox entry written, `agent.abort()` called, `stuckReason = 'repeated_tool_call'`.
+7. When `notify_only` is set: outbox written, abort NOT called.
+8. When `noProgressAbortEnabled: true` and `no_progress` fires with `stuckAbortPolicy !== 'notify_only'`:
+   same abort + outbox write.
+9. Return path returns `{ _tag: 'stuck', ... }` before `timeoutReason` check.
+10. `trigger-router.ts` `route()` and `dispatch()` handle `stuck` without assertNever fallthrough.
+11. `notification-service.ts` `buildNotificationBody()` and `buildDetail()` handle `stuck`.
+12. `NotificationPayload.outcome` union includes `'stuck'`.
+13. `makeSpawnAgentTool` handles `stuck` child result, returns `outcome: 'stuck'`.
+14. All 6 test cases in `workflow-runner-stuck-escalation.test.ts` pass.
+15. `npm run build` clean. `npx vitest run` no regressions.
+
+---
+
+## 3. Non-Goals
+
+- No `onStuck:` hook in TriggerDefinition (follow-up)
+- No console live panel stuck indicator
+- No `worktrain logs` formatting changes
+- No automatic retry on stuck
+- No Signal 5 (wall-clock at 80%) wiring
+- No new heuristics beyond Signal 1 and 2
+- No changes to `src/mcp/`
+- No `trigger-store.ts` parser changes
+
+---
+
+## 4. Philosophy-Driven Constraints
+
+- All new fields `readonly`
+- `issueSummaries` spread to new readonly array when included in return value
+- `writeStuckOutboxEntry` is fire-and-forget (void + catch)
+- `stuckReason` flag: first-writer-wins (same as `timeoutReason`)
+- Outbox write and abort are independent effects (write before abort gate check)
+
+---
+
+## 5. Invariants
+
+- **I1**: `ChildWorkflowRunResult` and `WorkflowRunResult` updates ship in the same commit.
+- **I2**: `stuckReason` is checked BEFORE `timeoutReason` in the return path.
+- **I3**: Outbox write fires regardless of `stuckAbortPolicy`.
+- **I4**: `no_progress` never aborts unless `noProgressAbortEnabled: true`.
+- **I5**: `repeated_tool_call` abort fires on the same turn as detection.
+- **I6**: First writer wins on `stuckReason` (guard: `stuckReason === null && timeoutReason === null`).
+
+---
+
+## 6. Selected Approach
+
+New `_tag: 'stuck'` discriminated union variant. Wire abort in `turn_end` subscriber
+after Signal 1 and Signal 2 emitter calls. Return stuck result before `timeoutReason`
+check. Update both union types atomically. Add `writeStuckOutboxEntry` module-level
+helper. Propagate to trigger-router, notification-service, makeSpawnAgentTool.
+
+**Runner-up rejected**: Extend `WorkflowRunTimeout.reason` -- violates make-illegal-states-unrepresentable.
+
+---
+
+## 7. Vertical Slices
+
+### Slice 1: Core types (workflow-runner.ts)
+- Add `WorkflowRunStuck` interface after `WorkflowRunTimeout`
+- Add to `WorkflowRunResult` union
+- Add to `ChildWorkflowRunResult` union (ATOMIC with above)
+- Add `stuckAbortPolicy?` and `noProgressAbortEnabled?` to `WorkflowTrigger.agentConfig`
+- **Done when**: `npm run build` clean after this slice
+
+### Slice 2: TriggerDefinition.agentConfig (types.ts)
+- Add `stuckAbortPolicy?` and `noProgressAbortEnabled?` after `maxTurns`
+- **Done when**: `npm run build` clean
+
+### Slice 3: Runtime wiring (workflow-runner.ts)
+- Add `sessionStartMs` constant after `maxTurns` resolution
+- Add `stuckReason` flag after `timeoutReason` flag
+- Add `writeStuckOutboxEntry` module-level helper
+- Wire abort after Signal 1 emitter call in `turn_end`
+- Wire abort after Signal 2 emitter call in `turn_end`
+- Add stuck return path before `timeoutReason` check
+- Update `makeSpawnAgentTool` resultObj type + add `stuck` arm before `assertNever`
+- **Done when**: `npm run build` clean
+
+### Slice 4: Caller propagation (trigger-router.ts, notification-service.ts)
+- Add `stuck` arm in `route()` exhaustive chain
+- Add `stuck` arm in `dispatch()` exhaustive chain
+- Add `'stuck'` to `NotificationPayload.outcome` union
+- Add `stuck` case in `buildNotificationBody()`
+- Add `stuck` case in `buildDetail()`
+- **Done when**: `npm run build` clean
+
+### Slice 5: Tests
+- Write `tests/unit/workflow-runner-stuck-escalation.test.ts` with 6 test cases
+- **Done when**: all 6 tests pass, no regressions
+
+---
+
+## 8. Test Design
+
+File: `tests/unit/workflow-runner-stuck-escalation.test.ts`
+
+Pattern: replicate turn_end subscriber logic (same as workflow-runner-stuck-detection.test.ts).
+
+**Test 1**: `stuckAbortPolicy: 'abort'` default -- repeated_tool_call fires, stuckReason set, abort called, would return _tag:'stuck'
+**Test 2**: `stuckAbortPolicy: 'notify_only'` -- abort NOT called, emitter still fires
+**Test 3**: `noProgressAbortEnabled: false` default -- no_progress does NOT set stuckReason
+**Test 4**: `noProgressAbortEnabled: true` -- no_progress sets stuckReason = 'no_progress', abort called
+**Test 5**: Compile-time assignability test: `WorkflowRunStuck` is assignable to `ChildWorkflowRunResult`
+**Test 6**: trigger-router exhaustive switch handles 'stuck' (import trigger-router, verify no assertNever path hit)
+
+---
+
+## 9. Risk Register
+
+| Risk | Likelihood | Severity | Mitigation |
+|------|------------|----------|------------|
+| ChildWorkflowRunResult not updated atomically | Low | High | Single-PR, Slice 1 includes both updates, Test 5 catches gap |
+| NotificationPayload.outcome union gap | Low | Medium | Slice 4 adds 'stuck'; build catches it |
+| stuckReason/timeoutReason race | Low | Low | Guard condition (both null check) |
+| writeStuckOutboxEntry silent failure | Low | Low | Fire-and-forget with console.warn |
+
+---
+
+## 10. PR Packaging Strategy
+
+Single PR: `feat/stuck-escalation`
+Single atomic commit with all 4 source files + test file.
+PR title: `feat(daemon): WorkflowRunStuck result variant with abort and outbox notification`
+
+---
+
+## 11. Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|-------|-----------|--------|
+| Slice 1 (types) | Make illegal states unrepresentable | Satisfied |
+| Slice 1 (types) | Exhaustiveness everywhere | Satisfied |
+| Slice 1 (types) | Type safety as first line of defense | Satisfied (ChildWorkflowRunResult updated) |
+| Slice 3 (runtime) | Errors are data | Satisfied |
+| Slice 3 (runtime) | Determinism over cleverness | Satisfied (simple flag) |
+| Slice 3 (runtime) | Fire-and-forget side effects | Satisfied (outbox write) |
+| Slice 4 (callers) | Exhaustiveness everywhere | Satisfied (all assertNever guards updated) |
+| Slice 5 (tests) | Prefer fakes over mocks | Satisfied (replicate subscriber logic, not vi.mock) |
+
+---
+
+**unresolvedUnknownCount**: 0
+**planConfidenceBand**: High
+**estimatedPRCount**: 1

package/docs/ideas/backlog.md

@@ -6395,3 +6395,89 @@ When a post-implementation MR review finds a UI/UX finding (wrong affordance, mi
 ### Priority
 
 Design this as part of the adaptive coordinator (#3). The `touchesUI` flag belongs on the classification output alongside `taskComplexity` and `maturity`. The UI detection logic and the design workflow insertion are both coordinator-level concerns, not engine-level.
+
+---
+
+## Current state update (Apr 20, 2026)
+
+**npm version: v3.45.0**
+
+### What shipped in this session (Apr 19-20, 2026)
+
+All five top-priority autonomous pipeline items shipped:
+
+- ✅ **#1 -- Worktree isolation + auto-commit** (PR #630) -- Each WorkTrain coding session now runs in an isolated git worktree (`~/.workrail/worktrees/<sessionId>`). `trigger.workspacePath` is never mutated; all tool factories receive `sessionWorkspacePath`. Crash recovery sidecar persists `worktreePath` for orphan cleanup. `delivery-action.ts` asserts HEAD branch before push. `test-task` trigger: `branchStrategy: worktree`, `autoCommit: true`, `autoOpenPR: true`.
+
+- ✅ **#2 -- Stuck detection escalation** (PR #636) -- New `WorkflowRunResult._tag: 'stuck'` discriminant. When `repeated_tool_call` heuristic fires and `stuckAbortPolicy !== 'notify_only'` (default: `'abort'`), daemon aborts the session immediately instead of burning the 30-min wall clock. Writes structured entry to `~/.workrail/outbox.jsonl`. `stuckAbortPolicy` and `noProgressAbortEnabled` configurable per trigger in `agentConfig`. `ChildWorkflowRunResult` updated atomically.
+
+- ✅ **#3 -- Adaptive pipeline coordinator** (PR #639) -- `worktrain run pipeline --issue N --workspace path` routes tasks to the right pipeline via pure static routing:
+  - dep-bump + PR number → QUICK_REVIEW (delegates to `runPrReviewCoordinator`)
+  - PR/MR number → REVIEW_ONLY
+  - `current-pitch.md` exists → IMPLEMENT (coding + PR + review + merge)
+  - Default → FULL (discovery → shaping → coding → PR → review → merge)
+  - Fix loop cap: 2 iterations max. Escalating audit chain for Critical findings. UX gate for UI-touching tasks. 6 hardcoded timeout constants. Pitch archived after IMPLEMENT/FULL completes.
+
+- ✅ **#4 -- GitHub issue queue poll trigger** (PR #637) -- New `github_queue_poll` trigger provider. Polls GitHub issues matching `GitHubQueueConfig` (assignee-based MVP, `label`/`mention`/`query` typed but `not_implemented`). Maturity inference from 3 deterministic heuristics. Idempotency check (conservative: parse errors = active). JSONL decision log at `~/.workrail/queue-poll.jsonl`. `maxTotalConcurrentSessions` cap. Bot identity config (`botName`, `botEmail`).
+
+- ✅ **#5 -- Context assembly layer** (PR #624, shipped earlier) -- `ContextAssembler` injects git diff summary + prior session notes before turn 1. Feeds into coordinator pre-dispatch.
+
+- ✅ **Performance sweep** (all 10 issues #248-257 -- already confirmed complete)
+- ✅ **Console session tree** (PR #607 -- parentSessionId rendered in UI)
+- ✅ **Daemon file-nav tools** (PR #619) -- Glob, Grep, Edit + upgraded Read/Write with staleness guard
+- ✅ **`spawn_agent` artifacts** (PR #613) -- `lastStepArtifacts` surfaced through spawn_agent return
+- ✅ **`wr.shaping` workflow** (PR #610) -- faithful Shape Up shaping, 9 steps
+- ✅ **Coding workflow Phase 0.5** (PR #610) -- upstream context detection, three-workflow pipeline
+
+### WorkTrain current capabilities (v3.45.0)
+
+**Autonomous workflow execution -- confirmed working:**
+- `worktrain run pipeline --issue N` routes to the right pipeline and runs it end-to-end
+- `worktrain run pr-review` autonomous PR review with structured verdicts and auto-merge
+- Coding sessions run in isolated worktrees, auto-commit, auto-open PR
+- Sessions abort when stuck (instead of burning 30-min wall clock)
+- GitHub issue queue polling: assign issue to `worktrain-etienneb` → daemon picks it up automatically
+- All sessions start with git diff + prior session notes injected (ContextAssembler)
+- Daemon file-nav tools: Glob, Grep, Edit, Read (paginated), Write (staleness guard)
+- Escalating audit chain: Critical findings → prod audit → re-review → escalate if still Critical
+- Fix loop: minor findings → max 2 fix iterations before escalation
+
+**WorkTrain agent tool set (v3.45.0):**
+`complete_step`, `continue_workflow` (deprecated), `Bash`, `Read`, `Write`, `Glob`, `Grep`, `Edit`, `report_issue`, `spawn_agent`, `signal_coordinator`
+
+**Trigger system:**
+- Generic webhook, GitLab MR polling, GitHub Issues polling, GitHub PR polling
+- **NEW: `github_queue_poll`** -- assignee-based issue queue with maturity inference
+- `branchStrategy: worktree` -- isolated worktree per session
+- `autoCommit: true` / `autoOpenPR: true` -- full delivery pipeline
+- `stuckAbortPolicy: 'abort' | 'notify_only'`
+- `goalTemplate`, `referenceUrls`, `contextMapping`, `agentConfig`
+
+### Accurate limitations (v3.45.0)
+
+1. **`dispatchAdaptivePipeline()` not yet connected** -- `TriggerRouter.dispatchAdaptivePipeline()` exists but `polling-scheduler.ts` still calls `router.dispatch()`. Queue poll sessions run as generic sessions, not routed through the adaptive coordinator. Cross-PR gap documented with TODO.
+
+2. **`findingCategory` not on review-verdict** -- Audit chain always dispatches `production-readiness-audit` for Critical findings regardless of finding type. `findingCategory` field on `findings[]` items needs to be added to `wr.review_verdict` schema as a follow-up so architecture findings can route to `architecture-scalability-audit` correctly.
+
+3. **Bot account setup required before first queue run** -- `worktrain-etienneb` GitHub account must be created, PAT generated with `repo:read` scope, stored as `WORKTRAIN_BOT_TOKEN`, and added as repo collaborator. Commit identity: `worktrain-etienneb@users.noreply.github.com`. Without this, `github_queue_poll` trigger has no bot identity.
+
+4. **No auto-merge setting in `worktrain init`** -- Auto-merge policy is hardcoded in the coordinator. Should be a `~/.workrail/config.json` setting exposed during `worktrain init`.
+
+5. **Grooming loop not built** -- Three open design decisions must be settled before building (human-ack boundary, compute budget, priority signal source). Deferred until Level 1 usage data exists.
+
+6. **Knowledge graph not wired** -- `src/knowledge-graph/` module exists (DuckDB + ts-morph), `ts-morph` in devDependencies. No daemon tool yet. Architecture decision: belongs in context assembly layer, not as a daemon tool.
+
+7. **`worktrain inbox --watch` stub** -- Prints "not yet implemented." The outbox mechanism exists; just needs a polling loop.
+
+8. **Artifact store not built** -- Agents dump markdown in the repo. `~/.workrail/artifacts/` not created.
+
+### Next priorities (groomed Apr 20)
+
+1. **Connect `dispatchAdaptivePipeline()`** -- Wire `polling-scheduler.ts` to call `TriggerRouter.dispatchAdaptivePipeline()` when `context.taskCandidate` is present. Small change, unlocks the full autonomous queue → pipeline connection.
+
+2. **`findingCategory` on review-verdict schema** -- Add `findingCategory: 'correctness' | 'security' | 'architecture' | 'ux' | 'performance' | 'testing'` to `findings[]` in `ReviewVerdictArtifactV1Schema`. Update `mr-review-workflow-agentic` final step to emit it. Unlocks correct audit routing.
+
+3. **Bot account setup + `worktrain init` overhaul** -- Create `worktrain-etienneb`, add `worktrain daemon --check` command (API key + git fetch dry run), expose auto-merge policy in `worktrain init`.
+
+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.

package/package.json

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