@exaudeus/workrail 3.40.0 → 3.42.0

package/docs/ideas/backlog.md

@@ -5891,3 +5891,359 @@ Coordinator logic:
 - Phase 1: coordinator scripts withhold `complete_step` advancement until the condition is met. This already works today -- the coordinator just doesn't advance the session until the fix agent is done.
 - Phase 2: the coordinator passes structured context when advancing: `complete_step(session, { injectedContext: fixSummary })`. The session receives it as part of the next step's prompt.
 - Phase 3: declarative pipelines -- workflow JSON declares that step N waits for an external condition before proceeding. The coordinator reads this and manages the timing automatically. No hand-coded coordinator script needed for common patterns.
+
+---
+
+### Coordinatable workflow steps: confirmation points the coordinator can satisfy (needs discovery, Apr 18, 2026)
+
+⚠️ **Needs discovery before implementation. The questions below are open, not answered.**
+
+**The insight:** workflows already have `requireConfirmation: true` on certain steps -- these are natural coordination points. Right now they pause for a human. The idea is to make them also pausable-for-a-coordinator, so a coordinator (or another agent) can be the one that responds instead of a human.
+
+**The vision:**
+A workflow reaches a `requireConfirmation` step. In MCP mode (human-driven), it behaves exactly as today -- pauses and waits. In daemon/coordinator mode, instead of blocking forever, the coordinator can:
+- Inject a synthesized answer based on external work it just did ("architecture review found X, proceed with approach A")
+- Spawn another agent to generate the answer and inject its output
+- Ask a discovery agent to weigh in and forward the result
+- Simply forward a human's message from the message queue
+
+The original session never knows whether a human or a coordinator satisfied the confirmation. It just receives the next turn with context.
+
+**Why this is powerful:**
+Today the coordinator is external to the workflow -- it orchestrates sessions from outside. This makes the workflow itself coordinatable from within, so multi-agent collaboration can be declared in the workflow spec rather than bolted on in coordinator scripts.
+
+**What's unknown and needs discovery:**
+1. **Mechanism:** is this an enriched `requireConfirmation` (add a `coordinatable: true` flag?), a new step type (`requireCoordinatorInput`?), or something at the engine level? Tradeoffs between each.
+2. **What gets injected:** always a structured decision ("proceed/revise/abort + findings"), or also data injection ("here are the file contents", "here's what the API returned")? How does the step receive it -- as a new tool call result, as a steer, as part of the step prompt?
+3. **Coordinator discovery:** how does the coordinator know a step is waiting for it vs waiting for a human? Does it poll the session state? Does the session emit a `coordinator_gate_pending` event? (This connects to the `waitForCoordinator` spec in this backlog.)
+4. **Timeout/fallback:** if the coordinator never responds, what happens? Fall back to human? Error? Configurable?
+5. **MCP invariant:** must behave identically to today in MCP/human-driven mode. The coordinator path is additive, not a behavior change for existing users.
+
+**Relationship to other specs:**
+- "Long-running sessions: stay open across agent handoffs" -- the session pauses at the confirmation point, coordinator acts, session resumes
+- "POST /api/v2/sessions/:id/steer" -- this might be the injection mechanism
+- `signal_coordinator` tool -- the session might signal the coordinator instead of blocking
+- `waitForCoordinator` step flag (already in this backlog) -- same underlying need, different framing
+- "Coordinator review mode: self-healing vs comment-and-wait" -- confirmation points are where that routing decision gets expressed
+
+---
+
+## Architecture Decision: Three-Workflow Pipeline (Apr 18, 2026)
+
+### Decision
+
+The canonical WorkRail workflow pipeline for new features is:
+
+```
+wr.discovery (optional) → wr.shaping (optional) → coding-task-workflow-agentic
+```
+
+Each workflow is independently useful. The pipeline is an optional chain, not a required sequence.
+
+### Rationale
+
+**wr.discovery** produces a direction -- what problem is worth solving. Output: structured discovery notes at `.workrail/discovery/`.
+
+**wr.shaping** produces a bounded pitch -- what specifically to build and explicitly NOT build, at a product level. Output: `.workrail/current-pitch.md`. Faithful Shape Up methodology. Tech-agnostic. No code-level content.
+
+**coding-task-workflow-agentic** produces running code -- engineering approach, sliced implementation, verification. When pitch.md exists (Phase 0.5), it skips design ideation and translates the pitch directly into an engineering approach. The pitch's no-gos and appetite are binding constraints.
+
+### No TechSpec workflow needed
+
+The coding workflow already does everything a TechSpec workflow would do: Phase 1b generates design candidates, Phase 1c selects and challenges the approach, Phase 3 writes the spec and implementation plan. Adding a separate TechSpec workflow would duplicate this and create a question of which is canonical. The coding workflow is the engineering planning layer.
+
+**The split that matters is product vs engineering:**
+- Product decisions (what to build, for whom, within what time) → wr.shaping
+- Engineering decisions (how to build it, which interfaces, which tests) → coding workflow
+
+### When to skip shaping
+
+- Task is small, concrete, and clearly scoped → go straight to coding workflow
+- Discovery already produced a bounded, implementable direction
+- You have a pre-written ticket or spec that already defines what to build
+
+### Faithful Shape Up constraint
+
+wr.shaping is tech-agnostic. A pitch for a Kotlin Android app and a pitch for a Python API service look structurally identical. No file paths, no function signatures, no implementation details. This makes pitches usable by human engineering teams at companies using Shape Up, not just WorkRail's coding workflow.
+
+### Phase 0.5 mechanics
+
+When `coding-task-workflow-agentic` finds `.workrail/current-pitch.md`:
+1. Reads all five pitch sections (Problem, Appetite, Solution/Elements, Rabbit Holes, No-Gos)
+2. Sets `shapedInputDetected=true`
+3. Skips phases 1a-1c (hypothesis, design generation, challenge-and-select)
+4. Phase 1d translates pitch elements/invariants/no-gos into an engineering approach
+5. Plan audit (Phase 4) checks for drift against the pitch
+6. Appetite is a hard ceiling -- oversized engineering work becomes follow-up tickets
+
+
+---
+
+## Idea: `context-gather` Step Type (Apr 19, 2026)
+
+### Problem
+
+Phase 0.5 in the coding workflow currently looks for a shaped pitch by checking a local path. This doesn't handle: coordinator-injected context, manually written docs (GDoc, Confluence, Notion), Glean-indexed artifacts, or URLs embedded in the task description. The search logic is duplicated if other workflows need the same document.
+
+### Proposed primitive
+
+A new engine-level step type `context-gather` that resolves a named context artifact from ordered sources:
+
+```json
+{
+  "type": "context-gather",
+  "id": "gather-pitch",
+  "contextType": "shaped-pitch",
+  "outputVar": "shapedInput",
+  "optional": true,
+  "sources": ["coordinator-injected", "local-paths", "task-url", "glean"]
+}
+```
+
+**Source resolution order (stops at first hit):**
+1. `coordinator-injected` -- coordinator already attached context of this type to the session (most common in autonomous mode)
+2. `local-paths` -- check `.workrail/current-pitch.md`, `pitch.md`, `PRD.md`, `.workrail/pitches/` (most recent)
+3. `task-url` -- extract any URL from the task description and fetch via WebFetch or matching MCP (GDoc, Confluence, Notion)
+4. `glean` -- search Glean for recent docs matching the task keywords and `contextType`; opt-in only (risk of false positives silently constraining wrong scope)
+
+If `optional: true` and no source resolves: `outputVar = null`, workflow continues normally.
+
+### Why engine-level, not a routine
+
+- Coordinator intercept requires the engine to check "has this type already been provided?" before running any search -- a routine can't express that
+- `contextType` is a declared intent multiple workflows can share (`wr.shaping`, `coding-task-workflow`, `wr.discovery`) without duplicating resolver logic
+- New sources (Linear, Jira, Notion) get added to the engine once, immediately available to all workflows
+
+### Relationship to existing work
+
+- Replaces/supersedes Phase 0.5's current local-path check in `coding-task-workflow-agentic`
+- Coordinator PR-review flow would inject `shaped-pitch` context before spawning the coding session
+- Any workflow that needs "find the spec/pitch/PRD for this task" uses the same step type
+
+### Open questions
+
+- How does the coordinator inject context into a session? Via a session variable set before `start_workflow`, or a new `inject_context` call?
+- How does `task-url` distinguish a GDoc URL from a Confluence URL from a Notion URL? MCP routing by domain?
+- What is the `contextType` vocabulary? Start with `shaped-pitch` -- what else? (`discovery-notes`, `design-spec`, `api-contract`?)
+- Glean false-positive risk: wrong document fed as shaped input silently constrains wrong scope. Needs confidence threshold or explicit user confirmation when Glean is the only hit.
+
+
+---
+
+## Completed (Apr 19, 2026)
+
+### wr.shaping -- Faithful Shape Up shaping workflow
+
+Created `workflows/wr.shaping.json`. Faithful Shape Up methodology, tech-agnostic, produces `.workrail/current-pitch.md` only. Nine steps: ingest → frame gate → diverge (6 shapes, Verbalized Sampling) → converge → breadboard + elements → rabbit holes + no-gos → draft/critique loop → approval gate → write pitch.md. Two human gates with autonomous fallback. Appetite is calendar-time only (xs/s/m/l/xl). No code-level content -- a pitch for a Kotlin app and a pitch for a Python service look structurally identical.
+
+### coding-task-workflow-agentic -- Upstream context Phase 0.5
+
+Added Phase 0.5 "Locate Upstream Context" to `coding-task-workflow-agentic.json`. Format-agnostic: the agent uses whatever tools are available (repo search, WebFetch, Confluence/Notion/Glean MCPs, etc.) to find any upstream document -- pitch, PRD, BRD, RFC, design doc, user story, Jira epic, etc. Sets `upstreamSpecDetected` + `solutionFixed` flags. When `solutionFixed=true`, design ideation phases (1a-1c) are skipped and Phase 1d translates upstream constraints directly into an engineering approach. Plan audit (Phase 4) checks for drift against `upstreamBoundaries` whenever an upstream document was found.
+
+Also consolidated from three workflow variants to one canonical file.
+
+
+---
+
+## Current state update (Apr 19, 2026)
+
+**npm version: v3.40.0**
+
+### What shipped since v3.36.0 (Apr 18 -- Apr 19)
+
+- ✅ **`wr.shaping`** -- faithful Shape Up shaping workflow (9 steps, two human gates with autonomous fallback)
+- ✅ **`coding-task-workflow-agentic` Phase 0.5** -- upstream context detection; skips design phases when solution is pre-specified. Three-workflow pipeline: shaping → discovery → coding.
+- ✅ **Coding workflow consolidated** -- from three variants (lean, full, lean.v2) to one canonical file.
+- ✅ **HttpServer removed from MCP server** (#601) -- pure stdio. MCP server can no longer accidentally start an HTTP server.
+- ✅ **Late-bound goals** (#604) -- `goalTemplate: "{{$.goal}}"` defaults for webhook-driven sessions. Goals can come from the payload, not just the static trigger definition.
+- ✅ **Coordinator message queue drain** (#606) -- `pr-review` coordinator reads `~/.workrail/message-queue.jsonl` before each spawn cycle. `worktrain tell stop`, `skip-pr <n>`, `add-pr <n>` work.
+- ✅ **Notifications shipped** -- `NotificationService` implemented, wired into `TriggerRouter` via `trigger-listener.ts`. `WORKTRAIN_NOTIFY_MACOS=true` and `WORKTRAIN_NOTIFY_WEBHOOK=<url>` in `~/.workrail/config.json`.
+- ✅ **`worktrain run pr-review`** -- fully wired coordinator command. `spawnSession` → `awaitSessions` → `getAgentResult` (session-wide artifact aggregation) → `parseFindingsFromNotes` → route by severity.
+- ✅ **`wr.review_verdict` artifact path** -- end-to-end wired: `mr-review-workflow.agentic.v2.json` phase-6 emits it, `artifact-contract-validator.ts` validates it at `continue_workflow` time, coordinator reads it with keyword-scan fallback.
+- ✅ **`worktrain logs` / `worktrain health`** -- structured daemon log tailing and per-session health summary. `worktrain status <id>` deprecated in favor of `worktrain health <id>`.
+- ✅ **`signal_coordinator` tool** -- agent can emit structured mid-session signals (`progress`, `finding`, `data_needed`, `approval_needed`, `blocked`) without advancing the step.
+- ✅ **`ChildWorkflowRunResult` + `assertNever`** -- spawn_agent delivery_failed bug fixed. `delivery_failed` impossible state is compile-time excluded.
+- ✅ **`lastStepArtifacts` on `WorkflowRunSuccess`** -- `onComplete` callback forwards artifacts alongside notes. Coordinator can read typed artifacts from result without a separate HTTP call.
+- ✅ **`steerRegistry` + POST `/sessions/:id/steer`** -- coordinator injection endpoint wired in daemon console. Running sessions register a steer callback; coordinators can inject mid-session messages via HTTP.
+- ✅ **GitHub polling adapters** -- `github_issues_poll` and `github_prs_poll` providers fully implemented alongside existing `gitlab_poll`.
+- ✅ **Knowledge graph spike** -- `src/knowledge-graph/` module: DuckDB in-memory + ts-morph indexer + two validation queries. NOT yet wired to an MCP tool (ts-morph in devDependencies).
+- ✅ **`worktrain daemon --install`** -- launchd plist creation, load, verify. Daemon survives MCP server reconnects.
+- ✅ **Performance sweep** -- April 2026 sweep identified 10 highest-leverage fixes, filed as issues #248-257. Not yet merged.
+
+### Accurate limitations (as of v3.40.0)
+
+1. **Console session tree UI not built** -- `parentSessionId` is stored in the `session_created` event and in `WorkflowRunSuccess`. Console `RunLineageDag` shows the per-session step DAG only. Cross-session parent-child tree is data-only. PRs #607 (tree view) and #608 (steer endpoint) are OPEN.
+2. **Daemon tool set is minimal** -- agent has: `complete_step`, `continue_workflow` (deprecated), `Bash`, `Read`, `Write`, `report_issue`, `spawn_agent`, `signal_coordinator`. No `Glob`, `Grep`, or `Edit`. Read/Write are thin wrappers.
+3. **`worktrain tell` messages only drained by coordinator** -- `drainMessageQueue` is called by `runPrReviewCoordinator`, not by the daemon loop. A running autonomous session cannot receive mid-run injections from `worktrain tell`. The `steerRegistry` HTTP endpoint is the mid-session channel.
+4. **Knowledge graph not wired** -- module exists, ts-morph must move to dependencies before an MCP tool can be built.
+5. **`spawn_agent` return missing `artifacts`** -- returns `{ childSessionId, outcome, notes }` only. Typed artifacts from child session are not surfaced to the parent agent. `lastStepArtifacts` on `WorkflowRunSuccess` exists but spawn_agent doesn't return it.
+6. **`worktrain inbox --watch` stub** -- `--watch` flag prints "not yet implemented" and exits.
+7. **Artifact store not built** -- agents still dump markdown/files directly into the repo. `~/.workrail/artifacts/` directory structure not created.
+8. **Performance issues not fixed** -- issues #248-257 filed from April sweep. `continue_workflow` triggers 6+ event log scans, full session rebuild per `/api/v2/sessions` request, N+1 workflow fetches, no caching.
+9. **No auto-commit** -- agents can write code but do not commit, push, or open PRs autonomously.
+10. **Assessment gates not battle-tested** -- end-to-end flow with `outputContract: required: true` not validated in production use.
+
+### Open PRs to merge
+
+- **#607** `feat(console): add session tree view for coordinator sessions` -- cross-session parent-child hierarchy in console. Blocked on: `parentSessionId` data is in store but console routes need to surface it.
+- **#608** `feat(console): add POST /api/v2/sessions/:sessionId/steer for coordinator injection` -- NOTE: this endpoint is already implemented in `daemon-console.ts` via `steerRegistry`. PR #608 may be adding this to the MCP server console separately. Check before merging.
+- **#610** `feat(workflows): add wr.shaping` -- the shaping workflow. Ready to merge.
+- **#587** `fix(mcp): add assertNever exhaustiveness guard to TriggerRouter` -- likely already applied in codebase (ChildWorkflowRunResult assertNever is live). May be a duplicate or different scope. Check.
+
+### Next priorities (groomed Apr 19)
+
+1. **Merge #610 (wr.shaping)** -- ready. Workflow is implemented and in the branch.
+2. **Merge #587 (TriggerRouter assertNever)** -- quick fix, check if still relevant.
+3. **Review and merge #607 + #608** -- console tree view and steer endpoint. Verify #608 doesn't duplicate what's already live in daemon-console.ts.
+4. **Performance fixes** -- issues #248-257. Pick highest-leverage first: SessionIndex (#248) and console projection cache (#249) eliminate most of the repeated scans.
+5. **Daemon tool set: add Glob + Grep** -- agents routinely need to search files. `Read` + `Bash` grep is slow and lossy. Native `Glob` and `Grep` tools would make coding sessions more reliable.
+6. **`spawn_agent` artifacts gap** -- add `artifacts?: readonly unknown[]` to the return value. `lastStepArtifacts` is already on `WorkflowRunSuccess`; wiring it through is ~30 LOC.
+7. **Knowledge graph wiring** -- move `ts-morph` and `@duckdb/node-api` to dependencies, add `query_knowledge_graph` MCP tool.
+8. **Artifact store foundation** -- `~/.workrail/artifacts/` directory, write path in `complete_step`.
+
+---
+
+### wr.shaping workflow: shape messy problems into implementation-ready specs (needs authoring, Apr 18, 2026)
+
+**Status:** Design complete. Ready to author as a WorkRail workflow JSON.
+
+**Design docs:**
+- `docs/design/shaping-workflow-discovery.md` -- WorkRail-internal discovery findings
+- `docs/design/shaping-workflow-external-research.md` -- External research synthesis (Shape Up, LLM failure modes, artifact schema)
+
+**The gap this fills:** WorkRail has `wr.discovery` (divergent) and `coding-task-workflow-agentic` (convergent). Shaping is the missing middle -- converting messy discovery output into a bounded, implementation-ready spec without mid-implementation rabbit holes.
+
+**The 11-step skeleton (see design doc for full detail):**
+1. ingest_and_extract -- extract problem frames, forces, open questions
+2. **frame_gate** -- MANDATORY HUMAN GATE: confirm problem + appetite
+3. diverge_solution_shapes -- 4 parallel rough shapes with varied framings
+4. converge_pick -- SEPARATE JUDGE (different model/prompt): pick best shape
+5. breadboard_and_elements -- fat-marker breadboard + Interface/Invariant/Exclusion classification
+6. rabbit_holes_nogos -- adversarial: risks, mitigations, no-gos, assumptions
+7. context_pack_build -- file globs, reuse_utilities, conventions, do-not-touch boundaries
+8. example_map_and_gherkin -- Given/When/Then acceptance criteria + verification commands
+9. draft_pitch -- self-refine ×2, SEPARATE CRITIC (obfuscated authorship)
+10. **approval_gate** -- MANDATORY HUMAN GATE: approve, edit, or restart
+11. finalize_and_handoff -- schema validation, emit shape.json + pitch.md
+
+**The single most important design decision:** generator and critic run on structurally different prompts (ideally different model families). CoT and self-reflection alone do NOT mitigate anchoring or self-preference bias (Lou & Sun 2025; Panickssery et al. 2024).
+
+**Output artifact:** `shape.json` -- contains problem story, appetite (multi-dimensional: calendar + tokens + turns + files), breadboard, elements, context_pack (file boundaries + reuse_utilities), Gherkin acceptance criteria, rabbit holes, no-gos, decomposition with walking skeleton, assumptions_log, build_readiness_score.
+
+**Key insight for AI implementers:** LLMs need MORE explicit specs than humans on interfaces/invariants/file boundaries (no tacit knowledge, no scope-shame), but LESS explicit than junior humans on standard patterns. The dominant failure mode is confident architectural divergence -- working code that reinvents an existing utility. Context Pack (Step 7) directly prevents this.
+
+**Next action:** author `wr.shaping` as a WorkRail workflow JSON using workflow-for-workflows, then update `coding-task-workflow-agentic` Phase 0 to detect and consume `shape.json` when present.
+
+---
+
+## Coordinator architecture: separation of concerns (Apr 19, 2026)
+
+**Decision: defer knowledge graph implementation until the context assembly layer is designed.**
+
+### The god class problem
+
+`src/coordinators/pr-review.ts` is already ~500 LOC doing: session dispatch, result aggregation, finding classification, merge routing, message queue drain, and outbox writes. Adding knowledge graph queries, context bundle assembly, upstream doc fetching, and prior session lookups would make it a god class.
+
+"Coordinator" is not a class or a script -- it is a **layer** that orchestrates across multiple concerns. Those concerns need to be separated before we add more to them.
+
+### The right layering
+
+```
+Trigger layer         src/trigger/          receives events, validates, enqueues
+Dispatch layer        (TBD)                 decides which workflow + what goal
+Context assembly      (TBD)                 gathers and packages context before spawning
+Orchestration layer   src/coordinators/     spawns, awaits, routes, retries, escalates
+Delivery layer        src/trigger/delivery  posts results back to origin systems
+```
+
+**Context assembly** is the missing layer. Before dispatching a coding session, something needs to:
+- Run `buildIndex()` and query "what imports the file being changed"
+- Find the upstream pitch/PRD/BRD for the task
+- Pull relevant prior session notes
+- Package everything as a structured context bundle
+
+This is NOT the orchestration script's job. The orchestration script should call `assembleContext(task, workspace)` and receive a bundle -- it should not know how that bundle was gathered.
+
+### Why the knowledge graph belongs in context assembly, not in the daemon
+
+Two options were considered:
+- **Daemon tool** (`makeQueryKnowledgeGraphTool` in `workflow-runner.ts`) -- agent queries mid-session on demand
+- **Coordinator pre-fetch** -- coordinator runs queries before spawning, injects answers as context
+
+The coordinator pre-fetch is better for known patterns (e.g. "what imports the file being changed" before a coding task). The agent doesn't need to know the graph exists -- it just gets the relevant facts as context. This also avoids adding `ts-morph` + DuckDB to the production build.
+
+The daemon tool approach is only better for ad-hoc mid-session queries the agent discovers dynamically. That's a secondary use case for v1.
+
+### What to build before the knowledge graph
+
+1. **Design the `ContextAssembler` abstraction** -- takes task description + workspace + trigger metadata, returns a structured context bundle. The knowledge graph is one of several sources (alongside upstream docs, prior session notes, repo state).
+2. **Refactor `pr-review.ts`** to use a `ContextAssembler` for the bits that fit there.
+3. **Then** implement knowledge graph as a `ContextAssembler` plugin -- not as a coordinator script addition and not as a daemon tool.
+
+### Anti-pattern to avoid
+
+Adding knowledge graph calls directly into `pr-review.ts` or any other coordinator script. That immediately creates the god class we're trying to avoid and couples the orchestration layer to a specific context source.
+
+---
+
+## Scheduled tasks (Apr 19, 2026)
+
+**The idea:** WorkTrain runs tasks on a schedule -- not triggered by an external event, but by time. "Every Monday morning, run the code health scan." "Every night at 2am, check for new GitHub issues and triage them." "First of the month, run the production readiness audit."
+
+### Why this matters for the autonomous pipeline vision
+
+The full autonomous pipeline (prioritize → discover → shape → implement → test → PR → review → fix → merge) needs a way to start without a human pushing a button. Scheduled tasks are the trigger layer for proactive, time-driven work. Without them, WorkTrain is purely reactive -- it only acts when a webhook fires or a human dispatches it.
+
+### What exists today
+
+The trigger system (`src/trigger/`) supports `generic` (webhook) and polling providers (`gitlab_poll`, `github_issues_poll`, `github_prs_poll`). There is no native cron/schedule provider. The workaround today is OS crontab calling `curl` to fire a webhook.
+
+### What to build
+
+A `schedule` provider in triggers.yml:
+
+```yaml
+triggers:
+  - id: weekly-code-health
+    provider: schedule
+    cron: "0 9 * * 1"          # every Monday at 9am
+    workflowId: architecture-scalability-audit
+    workspacePath: /path/to/repo
+    goal: "Run weekly code health scan -- identify coupling violations, complexity hotspots, and performance anti-patterns introduced this week"
+
+  - id: nightly-issue-triage
+    provider: schedule
+    cron: "0 2 * * *"          # every night at 2am
+    workflowId: wr.discovery
+    workspacePath: /path/to/repo
+    goal: "Review open GitHub issues created in the last 24 hours and triage them: classify severity, identify duplicates, suggest which to prioritize"
+
+  - id: backlog-next-task
+    provider: schedule
+    cron: "0 8 * * 1-5"        # weekday mornings at 8am
+    workflowId: coding-task-workflow-agentic
+    workspacePath: /path/to/repo
+    goal: "Pick the highest-priority unstarted task from docs/ideas/backlog.md and implement it"
+```
+
+### Key design decisions
+
+- **Cron syntax**: standard 5-field cron (`min hour dom month dow`). Parsed by `node-cron` or equivalent -- already a pattern in the codebase (backlog mentions cron).
+- **Timezone**: configurable per trigger, defaults to system timezone. Important for "weekday morning" schedules that need to fire in the user's timezone.
+- **Missed runs**: if the daemon was down when a scheduled run should have fired, it does NOT catch up on missed runs by default. "Run at 9am Monday" means "run the next time 9am Monday arrives." Optional `catchUp: true` flag for cases where missing a run should be recovered.
+- **Overlap prevention**: if a scheduled run fires while the previous run is still active, it should be skipped (not queued). A `coding-task` that takes 2 hours should not spawn a second instance at the next cron tick.
+- **Manual trigger**: `worktrain run schedule <trigger-id>` to fire a scheduled trigger immediately without waiting for the cron time. Useful for testing.
+
+### Integration with the autonomous pipeline
+
+Scheduled tasks are the entry point for fully autonomous work:
+- "Every weekday morning, pick the next backlog item and run the full pipeline" -- this is how WorkTrain improves WorkTrain without any human input.
+- "Every time a PR is opened, run the MR review pipeline" -- this is github_prs_poll, already exists.
+- "Every Monday, run the architecture audit and file GitHub issues for findings" -- new scheduled capability.
+
+### Implementation notes
+
+- The `PollingScheduler` in `src/trigger/polling-scheduler.ts` already runs time-based loops for GitLab/GitHub polling. The schedule provider would be a similar loop, using cron expression matching instead of API polling.
+- `node-cron` or `croner` npm package for cron expression parsing and next-fire-time calculation. Lightweight, no daemon dependencies.
+- Scheduled triggers have no webhook payload -- `contextMapping` is empty, `goalTemplate` uses only static text or env vars.
+- The schedule state (last-fired-at per trigger) persists to `~/.workrail/schedule-state.json` so the daemon can detect missed runs on restart.

package/docs/ideas/design-candidates-console-session-tree-impl.md

@@ -0,0 +1,64 @@
+# Design Candidates: Console Session Tree Implementation (Phase 3)
+
+*2026-04-18 -- This document covers only the remaining Slice 5 (SessionTreeView UI component)*
+*Phase 1 and Phase 2 artifacts: see design-candidates-session-tree-view.md and design-review-findings-session-tree-view.md*
+
+## Problem Understanding
+
+Slices 1-4 are implemented. The remaining work is Slice 5: add a SessionTreeView rendering path to SessionList.tsx.
+
+**Tensions:**
+- Expand toggle vs card navigation: two click targets on the same logical row. Resolved by a flex row with separate button elements.
+- Per-coordinator expand state vs pure component: expand state lives in useState (UI state, not business logic -- correct placement).
+- Auto-expand for in_progress: requires checking status in state initialization.
+
+**Likely seam:** SessionList.tsx (presenter) + session-list-use-cases.ts (pure function buildSessionTree, already built).
+
+**What makes it hard:** The expand toggle must be keyboard-navigable separately from the card AND must not trigger card navigation on click.
+
+## Philosophy Constraints
+
+- Pure presenter: no business logic in the component
+- Immutability: expand state is a ReadonlyMap or regular Map in useState
+- Functional/declarative: map SessionTreeNode[] to JSX
+- Compose with small functions: SessionTreeView as a named function, separate from SessionList
+
+## Impact Surface
+
+- SessionList.tsx: adding viewMode branch
+- session-list-use-cases.ts: already has buildSessionTree exported
+- session-list-reducer.ts: already has viewMode + view_mode_changed
+
+## Candidates
+
+### Candidate A: SessionTreeView inline in SessionList.tsx (only candidate)
+
+**Summary:** A `SessionTreeView` function component in SessionList.tsx takes `SessionTreeNode[]`, initializes expand state as `Map<string, boolean>` (auto-expand in_progress), and renders a flex row with [expand-toggle, coordinator-card] and children in a TreeLine wrapper below when expanded.
+
+**Tensions resolved:** Expand/navigate separation (separate button elements). Accepts: expand state resets on navigation (transient UI state is acceptable).
+
+**Boundary:** SessionList.tsx presenter layer.
+
+**Failure mode:** Expand toggle accidentally triggers card navigation. Fixed by: expand toggle button is outside the coordinator ConsoleCard, not nested inside it.
+
+**Repo pattern:** Follows SessionGroup component pattern in SessionList.tsx exactly.
+
+**Gains:** Simple, pure, testable in isolation. **Loses:** Expand state resets when navigating away (transient).
+
+**Scope:** Best-fit.
+
+**Philosophy:** All principles honored.
+
+## Comparison and Recommendation
+
+Single candidate; no comparison needed. Candidate A is the correct approach.
+
+## Self-Critique
+
+Strongest counter-argument: expand state should be in the reducer (durable within page session). Counter-counter: expand state is UI state, not domain state. Reducer is for interaction state that needs to persist across renders (search, filter, sort, pagination). Expand state for individual coordinator rows is more like accordion state -- local useState is correct.
+
+Pivot condition: if user feedback shows expand state loss is disruptive, move to reducer with `expanded_coordinators: ReadonlySet<string>` field.
+
+## Open Questions for the Main Agent
+
+None. Implementation is fully specified in docs/ideas/design-candidates-session-tree-view.md and the Phase 2 design spec.

package/docs/ideas/design-candidates-session-tree-view.md

@@ -0,0 +1,196 @@
+# Design Candidates: Session Tree View in Console
+
+*Discovery session: 2026-04-18*
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Flat API vs tree UI**: `/api/v2/sessions` returns a flat array. The UI wants a tree grouped by parent-child relationships. Options: build tree client-side from parentSessionId index, or change the API. The existing repo pattern (flat projection DTOs, pure use-case functions) favors building the tree client-side.
+
+2. **Orphaned children vs tree integrity**: If a parent session is older than MAX_SESSIONS_TO_LOAD=500, its children have a dangling parentSessionId. Showing orphaned children as roots is the only safe fallback, but the tree is incomplete. Acceptable for MVP.
+
+3. **Filtering with tree structure**: When filtering by status or search, should the parent appear if only a child matches? Naive filtering breaks the tree. Better approach: include parent when any child matches. Adds complexity to filterSessions().
+
+4. **Type mirror sync**: ConsoleSessionSummary is duplicated between `src/v2/usecases/console-types.ts` (server) and `console/src/api/types.ts` (client mirror). Both must be updated in sync. This is an existing technical debt, not new -- adding parentSessionId just adds one more field to keep in sync.
+
+### Likely Seam
+
+The seam is between the flat sessions array and the tree render. The right place is a new pure function `buildSessionTree(sessions)` in `session-list-use-cases.ts`, not a new HTTP endpoint and not a modification to the GROUP_AXES grouping infrastructure.
+
+### What Makes This Hard
+
+The existing GROUP_AXES abstraction in `session-list-use-cases.ts` is flat -- each group has a string label. Tree grouping requires a fundamentally different rendering shape: a clickable coordinator SessionCard as the group header, with indented children below. Shoehorning tree rendering into GROUP_AXES produces an illegal state (coordinator appears as both a plain-text header label AND a card inside the group).
+
+The filter-with-tree interaction is the hardest sub-problem: when tree mode is active, a filter that excludes the parent but matches a child must still show the parent as context.
+
+---
+
+## Philosophy Constraints
+
+From CLAUDE.md and repo patterns:
+
+- **Immutability by default**: all new types use readonly fields
+- **Pure functions in use-cases**: business logic in `session-list-use-cases.ts`, not in React components
+- **Make illegal states unrepresentable**: coordinator session must not appear twice (as header AND as card)
+- **Errors are data**: orphaned children (parent not in loaded set) should degrade gracefully to root-level display, never throw
+- **YAGNI**: 2-level tree only for MVP; no recursive structure needed
+- **Compose with small pure functions**: `buildSessionTree()` should be pure and independently testable
+- **Validate at boundaries**: `extractParentSessionId()` happens in console-service.ts (the projection boundary); frontend trusts the value
+
+**No philosophy conflicts found.** CLAUDE.md principles and repo patterns are consistent for this problem.
+
+---
+
+## Impact Surface
+
+If `ConsoleSessionSummary` gains a `parentSessionId` field:
+- `src/v2/usecases/console-types.ts` -- server type definition
+- `console/src/api/types.ts` -- client type mirror (must stay in sync manually)
+- `projectSessionSummary()` in `console-service.ts` -- new field returned in the projection
+- `filterSessions()` in `session-list-use-cases.ts` -- needs parentIndex for tree-mode filtering
+- `SessionList.tsx` -- new tree rendering path
+- Any future codegen for the type mirror would pick this up automatically
+
+Existing consumers of the flat `/api/v2/sessions` endpoint are unaffected -- the new field is additive and optional for root sessions.
+
+---
+
+## Candidates
+
+### Candidate A -- Minimal: add parentSessionId, reuse GROUP_AXES with a 'tree' option
+
+**Summary:** Add `parentSessionId` to both type files. Add a 'tree' option to GROUP_AXES that groups children under their parent's sessionId as the group key. The existing SessionGroup component shows the parent sessionId as the group label; children are SessionCards inside.
+
+**Tensions resolved:** API stability (flat array unchanged). Type sync (one field added to both).
+
+**Tensions accepted:** GROUP_AXES abstraction is abused. SessionGroup renders a plain-text label (the parent sessionId string), not a clickable coordinator SessionCard.
+
+**Boundary solved at:** Frontend GROUP_AXES layer only.
+
+**Why that boundary:** Minimum viable change -- no new components, no new functions.
+
+**Failure mode:** Coordinator session appears BOTH as the group label text AND as a SessionCard inside the group (it's in the flat list). The group header is a non-navigable string, not a card. This is an illegal state: the coordinator is visible twice in different forms. Fixing this requires adding a custom node-renderer to SessionGroup -- at which point you've rebuilt Candidate B anyway.
+
+**Repo pattern:** Abuses GROUP_AXES -- designed for grouping by string key, not parent-child hierarchies.
+
+**Gains:** Zero new components. Minimal diff.
+
+**Losses:** Visual quality. Coordinator not navigable from group header. No tree connector lines. Duplication bug.
+
+**Scope:** Too narrow -- doesn't deliver the tree view quality described in the backlog.
+
+**Philosophy:** YAGNI honored. Make illegal states unrepresentable violated (coordinator appears twice).
+
+---
+
+### Candidate B -- Best-fit: new buildSessionTree() + dedicated SessionTreeView component
+
+**Summary:** Add `parentSessionId: string | null` to `ConsoleSessionSummary` on server and client. Implement `extractParentSessionId(events)` in `console-service.ts` (O(1), session_created is always eventIndex=0). Add a new pure function to `session-list-use-cases.ts`:
+
+```typescript
+interface SessionTreeNode {
+  readonly session: ConsoleSessionSummary;
+  readonly children: readonly ConsoleSessionSummary[];
+}
+
+interface SessionTree {
+  readonly roots: readonly SessionTreeNode[];
+  readonly orphanChildIds: ReadonlySet<string>;
+}
+
+function buildSessionTree(sessions: readonly ConsoleSessionSummary[]): SessionTree
+```
+
+Add a view mode toggle (tree/flat) to `SessionListState`. When tree mode is active, render a new `SessionTreeView` component: coordinator cards at root level, children indented 20px with a CSS `border-left` connector line on the wrapper div. Orphans (parent not loaded) appear as roots.
+
+Modify `filterSessions()` to accept an optional `parentIndex: ReadonlyMap<string, string>` parameter. When tree mode is active: if a child matches the filter, include its parent too (parent appears even if it doesn't match the filter text/status).
+
+**Tensions resolved:** API stability. Tree rendering quality (no duplication). Orphan handling (explicit orphanChildIds set). Filter+tree interaction (parent included when child matches).
+
+**Tensions accepted:** Type mirror sync remains manual.
+
+**Boundary solved at:** Frontend use-cases layer (`buildSessionTree()` is pure) + new presenter component.
+
+**Why that boundary:** `buildSessionTree()` is pure and testable without React. The tree is computed once per render cycle, not per-card. Follows the exact same pattern as the existing pure functions in `session-list-use-cases.ts`.
+
+**Failure mode:** Filter-with-tree is the hardest case. The `filterSessions()` modification adds complexity. If the logic is wrong, the parent could be shown when it shouldn't (e.g., filter=complete, parent is in_progress, child is complete -- should the in_progress parent appear?). Decision: include parent when any child matches, regardless of parent's own status. This is the most useful behavior for the tree view use case.
+
+**Repo pattern:** Follows the pure use-cases + presenter pattern exactly. New SessionTreeView component follows the same presenter shape as existing components.
+
+**Gains:** Clean tree rendering with visual connectors. Navigable coordinator cards. No duplication. Pure testable logic. Degrades gracefully for orphaned children.
+
+**Losses:** Slightly more code than Candidate A. Two components for the same view (flat list + tree view).
+
+**Scope:** Best-fit -- delivers the design described in the backlog without overbuilding.
+
+**Philosophy:** All principles honored. Immutability, explicit domain types, pure functions, YAGNI (2-level tree only).
+
+---
+
+### Candidate C -- Server-side tree: new `GET /api/v2/sessions/tree` endpoint
+
+**Summary:** Add a new server endpoint that returns `{ roots: ConsoleSessionSummaryWithChildren[], orphans: ConsoleSessionSummary[] }`. The flat `/api/v2/sessions` endpoint is unchanged. Server builds the tree from the loaded session set, embedding children under their parent in the response.
+
+**Tensions resolved:** Tree structure computed at the source of truth (server, with access to the full 500-session window). Client receives a ready-to-render tree.
+
+**Tensions accepted:** New endpoint means new React Query hook, new cache key, new loading state. Two overlapping endpoints that must be kept consistent.
+
+**Boundary solved at:** Server projection layer (`console-service.ts`).
+
+**Why that boundary:** Server has the full session set in scope; client doesn't need to rebuild the tree from a flat list.
+
+**Failure mode:** API surface grows. The flat endpoint and tree endpoint must stay consistent. Cache invalidation logic must be updated for both. If the tree endpoint is slow (500 sessions), the flat endpoint is still fast -- users may not understand why.
+
+**Repo pattern:** Departs from the existing pattern (all console endpoints return flat projection DTOs). Adds server complexity for a problem that client-side pure functions can solve with zero HTTP overhead.
+
+**Gains:** Tree is always consistent (parent and children computed together). Client rendering is simpler -- just map the tree response.
+
+**Losses:** API surface growth. Additional React Query hook. More complex cache invalidation. Server-side complexity for a problem solvable client-side.
+
+**Scope:** Too broad -- the flat list already contains all the data needed to build the tree client-side.
+
+**Philosophy:** Conflicts with YAGNI (new endpoint not needed). Conflicts with validate-at-boundaries (boundary moved to server when client can handle it).
+
+---
+
+## Comparison and Recommendation
+
+| Tension | A | B | C |
+|---|---|---|---|
+| API stability | Resolves | Resolves | Adds new endpoint |
+| Tree rendering quality | Fails (duplication) | Resolves | Resolves |
+| Orphan handling | None | Explicit | Server-side |
+| Filter+tree interaction | Broken | Manageable | Handled server-side |
+| Repo pattern fit | Abuses GROUP_AXES | Follows pure-function pattern | Departs from flat-DTO pattern |
+| Reversibility | Easy | Easy | Medium |
+| Philosophy fit | Partial | Full | Partial |
+
+**Recommendation: Candidate B.**
+
+B resolves all real tensions without overbuilding. It follows the existing pure-function/presenter split the repo already practices. `buildSessionTree()` is pure and testable independently of React. The filter-with-tree interaction is manageable with a contained change to `filterSessions()`. The 2-level tree constraint matches the backlog's examples exactly.
+
+---
+
+## Self-Critique
+
+**Strongest argument against B:** What if the Phase 2 UX design requires 3-level trees (coordinator → child coordinator → grandchild)? B explicitly excludes this by using `readonly children: readonly ConsoleSessionSummary[]` instead of `readonly children: readonly SessionTreeNode[]`. Changing to recursive SessionTreeNode later is a contained change, but it would require updating the SessionTreeView component too.
+
+**Pivot conditions:**
+- If Phase 2 UX requires >2 levels: change `SessionTreeNode.children` to `readonly SessionTreeNode[]` and make `SessionTreeView` recursive. The `buildSessionTree()` function would need to become recursive as well.
+- If filter+tree interaction proves too complex: ship tree view without filter support in tree mode, show a "tree view disabled while filtered" state.
+- If the type mirror sync problem grows: introduce codegen for the type mirror (separate from this feature).
+
+**Assumption that would invalidate B:** If the flat `/api/v2/sessions` endpoint doesn't return all sessions needed to build a complete tree (e.g., if sessions are paginated server-side before reaching the client). Currently MAX_SESSIONS_TO_LOAD=500 applies before the response; if a coordinator and its children are all within the 500-session window, the tree will be complete. If the coordinator is old but children are recent, the tree will be incomplete -- but this degrades gracefully (children show as roots).
+
+---
+
+## Open Questions for the Main Agent
+
+1. **Filter behavior in tree mode**: When filtering by status=in_progress and the coordinator is complete but has an in_progress child -- should the coordinator appear? Proposed: yes, include parent when any child matches. Is this the right UX?
+
+2. **Tree mode default or opt-in**: Should the tree view be the default mode, or should users opt in via a toggle? Given that zero sessions have parentSessionId today, defaulting to tree view would show an identical flat list -- tree mode only activates when coordinator sessions exist.
+
+3. **Connector line style**: Simple `border-left` CSS on the indented container, or tree-line SVG connectors like `TreeLine.tsx` (which already exists in `console/src/components/TreeLine.tsx`)? The existing component should be used if it fits.