@exaudeus/workrail 3.33.0 → 3.34.1

package/docs/ideas/backlog.md

@@ -4390,3 +4390,364 @@ The existing `DaemonEventEmitter` (written in #498) writes to a separate daily l
 ### FatalToolError: distinguish recoverable from non-recoverable tool failures (follow-up from PR #523)
 The blanket try/catch in AgentLoop._executeTools() converts ALL tool throws to isError tool_results. This is correct for Bash/Read/Write (LLM can see and retry), but potentially wrong for continue_workflow failures (LLM retrying with a broken token loops). The discovery agent proposed a FatalToolError subclass: tools throw FatalToolError for non-recoverable errors (session corruption, bad tokens), plain Error for recoverable failures. _executeTools catches plain Error and returns isError; FatalToolError propagates and kills the session. Combined with the DEFAULT_MAX_TURNS cap (PR followup), this provides defense-in-depth.
 5. Deprecate `DaemonEventEmitter` once console reads from session events
+
+---
+
+### Worktree lifecycle management: automatic cleanup and inventory (Apr 18, 2026)
+
+**The problem:** every WorkTrain agent that uses `--isolation worktree` leaves a worktree on disk after completion. With 10 concurrent agents running all day, this accumulated to 69 worktrees in `.claude/worktrees/`, triggering hundreds of simultaneous `git status` processes that saturated the CPU.
+
+**What's needed:**
+
+1. **Automatic cleanup on session end** -- when a WorkTrain session completes (success or failure), the daemon automatically runs `git worktree remove <path> --force` for the session's worktree. If the branch is already merged to main, also delete the local branch ref.
+
+2. **Startup pruning** -- `workrail daemon` startup runs `git worktree prune` in each configured workspace before starting the trigger listener.
+
+3. **`worktrain worktree list`** -- shows all WorkTrain-managed worktrees: path, branch, session ID, age, whether the branch is merged.
+
+4. **`worktrain worktree clean`** -- removes all worktrees whose branches are merged to main, or older than N days. Dry-run mode by default.
+
+5. **`worktrain worktree status`** -- summary: how many worktrees, total disk usage, any stale ones.
+
+6. **Never use main as a worktree** (already in backlog) -- enforced at worktree creation time, not just as a rule.
+
+**Root cause of the CPU spike:** 69 worktrees × repeated `git status --short` from tools/IDE plugins = hundreds of concurrent git processes. Each `git status` on a large repo with many untracked files is CPU-intensive.
+
+**Mitigation already in place:** `--isolation worktree` creates branches named `worktree-agent-<id>` -- these are identifiable and bulk-deletable. The daemon's `runStartupRecovery()` could also prune them.
+
+**Build order:** startup pruning (trivial, high value) → automatic cleanup on session end → `worktrain worktree` CLI commands.
+
+---
+
+### Simplify MCP server: remove primary election, bridge, and HTTP serving (architectural cleanup)
+
+**The core insight:** the bridge/primary-election system exists solely to solve "only one process should serve the console UI on port 3456." Now that `worktrain console` is a standalone file-watching binary (PR #512), that problem is already solved. The entire bridge/election system can be removed.
+
+**What "allow multiple MCP processes" means in practice:**
+- Each Claude Code window gets its own MCP server -- no port contention, no primary election, no bridge reconnect cycles
+- MCP server becomes pure stdio: starts, handles tools, exits. Nothing async needs to write after the pipe closes -- EPIPE is irrelevant.
+- Session store is append-only JSONL per-session -- multiple processes writing different sessions cannot corrupt each other
+- `worktrain console` aggregates all sessions from the file store regardless of how many MCP servers ran
+
+**What to remove:**
+- `DashboardLock` / `tryBecomePrimary()` / `bindWithPortFallback()` -- the entire primary election system
+- `bridge-entry.ts` -- the bridge, spawn storm, and reconnect drama are gone
+- `HttpServer` starting as part of the MCP server -- console owns HTTP, not MCP
+
+**What remains for the MCP server:** pure stdio MCP protocol + session engine. No HTTP, no port binding, no lock files. Starts instantly, exits cleanly.
+
+**Why this is safe:**
+- Tokens are session-scoped UUIDs -- two servers cannot share a session
+- Append-only JSONL has no exclusive file locks
+- ~50MB per process × 3 Claude Code windows = 150MB -- acceptable
+
+**The bridge complexity was always a band-aid.** It was the right solution when the MCP server also owned the console UI. With the standalone console, the band-aid can come off and the system becomes dramatically simpler and more reliable.
+
+**Build order:** extract `worktrain console` fully (done) → remove HttpServer from MCP startup → remove bridge → remove DashboardLock/primary election → MCP server is pure stdio.
+
+---
+
+### Agent-engine communication: first principles design (Apr 18, 2026)
+
+**The setup for this conversation:**
+
+Three discovery agents investigated whether the daemon should continue using MCP-style tool calls for workflow control (`continue_workflow`). Their findings:
+
+- **Discovery 1**: Tool calls are fine; enrich `continue_workflow` with `artifacts` now, explore structured output hybrid later pending Bedrock verification. ~225 tokens/request saved with hybrid.
+- **Discovery 2**: `complete_step` tool -- daemon owns transitions, continueToken hidden from LLM, notes required at type level. Cleaner DX without paradigm shift.
+- **Discovery 3**: The field has converged on tool calls. OpenAI Agents SDK, LangGraph, Temporal, Vercel AI SDK all use tool calls for workflow control. WorkRail's `continue_workflow` with HMAC tokens is already field-standard or better.
+
+**User's response to "the field has converged on tool calls":**
+
+> "Right, but do we want industry standards? Aren't we trying to build something special? What if there is better?"
+
+This is the right question. "Field convergence" is a description of where everyone ended up starting from the MCP/function-calling paradigm -- not proof that it's optimal. Every system surveyed treats the workflow engine as external infrastructure the agent calls into. WorkRail is different: **the daemon IS the workflow engine**. The agent loop and the step sequencer run in the same process, sharing the same DI container. Tool calls are a network-origin concept -- they exist because there's an LLM over there and an executor over here. WorkRail doesn't have that constraint.
+
+---
+
+#### First-principles alternatives (unexplored territory)
+
+These were not in any of the discovery agents' outputs -- they emerge from the insight that WorkRail owns both sides of the conversation:
+
+**1. Structured response parsing (no tool call for workflow control)**
+The agent outputs a structured response at the end of each turn. The daemon parses it. The LLM never "calls a tool" to advance -- it produces a well-structured output and the daemon acts on it. The continueToken and workflow machinery are completely invisible to the LLM. Example: agent outputs `{"step_complete": true, "notes": "...", "artifacts": [...]}` as its final text, daemon detects this and advances.
+
+**2. Implicit advancement (criteria-based)**
+The daemon watches what the agent produces (file writes, bash outcomes, notes) and decides when to advance -- the agent never explicitly signals "I'm done." The workflow step has completion criteria, and the daemon evaluates them against the agent's cumulative output. More like a CI pipeline (tests pass = done) than an API call. The agent just works; the daemon decides when the step is complete.
+
+**3. Declarative intent + daemon execution**
+The agent outputs what it *wants* to happen: "I want to commit these files with this message and advance to the next step." The daemon executes. Same as the scripts-over-agent principle applied to the agent's own workflow control -- the agent declares intent, scripts execute. No tool call for the mechanical parts.
+
+**4. Streaming judgment**
+The daemon reads the agent's streaming response in real-time, extracts notes and artifacts as they appear, and makes the advance decision before the agent "finishes." No explicit signal from the agent. The daemon monitors and decides.
+
+**5. Separation of concerns: tools for world, declaration for workflow**
+Keep tool calls for external actions (Bash, Read, Write) -- these genuinely need interleaved execution and result reasoning. But workflow control (advance, submit artifacts, set context) uses a different mechanism entirely: structured response, implicit detection, or a single lightweight declaration. The protocol distinction: tools are for I/O, declarations are for state.
+
+---
+
+#### What makes this hard
+
+These alternatives trade off in important ways:
+- **Structured response parsing**: requires reliable structured output from the LLM, which can fail without explicit enforcement
+- **Implicit advancement**: requires the daemon to correctly evaluate completion criteria -- complex for open-ended steps
+- **Declarative intent**: still needs some kind of output format; essentially moves the "tool call" into the response text
+- **Streaming judgment**: hardest to implement correctly; requires the daemon to parse partial responses reliably
+
+The current tool-call approach works precisely because it's explicit: the agent signals intent exactly once, the daemon acts on it. The alternatives are more elegant but less reliable.
+
+---
+
+#### What to actually investigate
+
+Before committing to any alternative, these questions need answers:
+
+1. **Does Bedrock support `response_format + tools` simultaneously?** A 10-line test call resolves this. If yes, hybrid structured output is immediately viable for workflow control.
+2. **What does implicit advancement actually look like for a coding task?** Write out the completion criteria for `coding-task-workflow-agentic` phase-0 (classify). Can a daemon reliably detect "Phase 0 is done" without an explicit signal?
+3. **What is the actual failure mode of structured response parsing?** How often does Claude 4.6 Sonnet fail to produce valid JSON when asked to end its turn with a structured summary? Under what conditions?
+4. **What did nexus-core do?** The backlog notes nexus-core as a more advanced system -- how does it handle agent-step transitions?
+
+These are prototype questions, not design questions. Build the smallest possible test for each before committing to any direction.
+
+---
+
+### Bundled trigger templates: zero-config workflow automation via worktrain init (Apr 18, 2026)
+
+**Problem:** Every user has to write their own triggers.yml manually. Wrong workflow IDs, missing required fields, wrong workspace paths -- all common mistakes (we hit all three today). There's no "just works" path to workflow automation.
+
+**Solution:** Ship common trigger templates bundled with WorkTrain. `worktrain init` presents a menu and generates a pre-filled triggers.yml.
+
+**Bundled templates to ship:**
+
+```yaml
+# Template: mr-review
+- id: mr-review
+  workflowId: mr-review-workflow-agentic
+  goal: "Review the PR specified in the webhook payload goal field"
+  concurrencyMode: parallel
+  autoCommit: false
+  agentConfig: { maxSessionMinutes: 30 }
+
+# Template: coding-task  
+- id: coding-task
+  workflowId: coding-task-workflow-agentic
+  concurrencyMode: parallel
+  autoCommit: false
+  agentConfig: { maxSessionMinutes: 60 }
+
+# Template: discovery-task
+- id: discovery-task
+  workflowId: wr.discovery
+  concurrencyMode: parallel
+  autoCommit: false
+  agentConfig: { maxSessionMinutes: 60 }
+
+# Template: bug-investigation
+- id: bug-investigation
+  workflowId: bug-investigation.agentic.v2
+  agentConfig: { maxSessionMinutes: 45 }
+
+# Template: weekly-health-scan (cron, when native cron trigger ships)
+# - id: weekly-health-scan
+#   type: cron
+#   schedule: "0 9 * * 0"
+#   workflowId: architecture-scalability-audit
+```
+
+**`worktrain init` flow:**
+1. "Which workflows do you want to run automatically?" (checkbox menu)
+2. For each selected: set `workspacePath` to current directory (overridable)
+3. Generate `triggers.yml` in the workspace root
+4. Validate workflow IDs exist before writing (use the startup validator)
+5. Tell the user how to fire each trigger: `curl -X POST http://localhost:3200/webhook/<id> ...`
+
+**Why this matters:** The difference between WorkTrain being usable by anyone vs only by engineers who read the source code. A new user should be able to go from `worktrain init` to their first automated workflow in under 5 minutes.
+
+**Also needed:** `worktrain trigger add <template-name>` to add a single trigger to an existing triggers.yml without re-running init.
+
+---
+
+### Coordinator context injection standard: agents start informed, not discovering (Apr 18, 2026)
+
+**The problem:** subagents spawned by a coordinator are completely blind. They know nothing of prior conversations, existing docs, the pipeline, or what's already been tried. The workflows compensate by spending 3-5 turns on "Phase 0: context gathering" every session -- expensive in tokens, time, and LLM turns -- just to get oriented before work starts.
+
+**The root cause:** the coordinator spawns agents with task descriptions but not context. "Fix the Windows CI failures" is a task. "The Windows CI failures are in `workflow-runner-bash-tool.test.ts` because `node -e` isn't in PATH on Windows -- the fix is to use `process.execPath` instead of `node`, which is the established pattern in this codebase" is context. The difference is 0 discovery turns vs 5.
+
+**The standard to establish:**
+
+Every coordinator-spawned agent gets a pre-packaged context bundle. The coordinator assembles it before calling `worktrain spawn`. The bundle includes:
+
+1. **Prior session findings** -- what relevant sessions discovered (from session store query)
+2. **Established patterns** -- the specific invariants and patterns the agent needs (from knowledge graph or AGENTS.md)
+3. **What NOT to discover** -- explicit list of things already known so the agent doesn't waste turns
+4. **Failure history** -- what's been tried and didn't work (prevents re-exploring dead ends)
+
+**Format:** ~2000 tokens max, injected as a `<context>` block before the task description. Structured so the agent can skip Phase 0 context gathering entirely when the bundle is complete.
+
+**Build order:**
+1. Write the standard as a prompt template for coordinator scripts (`worktrain spawn` calls)
+2. The knowledge graph provides the infrastructure for querying relevant context automatically
+3. Eventually: `worktrain spawn` reads the context bundle from the graph + session store automatically, coordinator doesn't have to assemble it manually
+
+**Why this is high priority:** every agent spawned today without proper context is burning tokens on discovery that should have been provided upfront. At 10 concurrent agents, that's 10x the waste. With proper context injection, Phase 0 becomes 1 turn instead of 5, and output quality improves because the agent starts with the right mental model.
+
+---
+
+### Context budget per spawned agent: capped, structured, queryable (Apr 18, 2026)
+
+**The companion spec to context injection:**
+
+Rather than hoping agents discover the right context, the coordinator guarantees a minimum context budget: a pre-packaged bundle of ~2000 tokens that every agent starts with. The knowledge graph is what makes this scalable -- without it, the coordinator has to manually assemble context from files, which is itself expensive.
+
+**Bundle contents (structured):**
+- `<relevant_files>` -- paths + key excerpts from files the agent will likely touch (from KG query)
+- `<prior_sessions>` -- summaries of the last 3 sessions that touched related code (from session store)
+- `<established_patterns>` -- specific patterns the agent must follow (e.g. "use `tmpPath()` not `/tmp/`")
+- `<known_facts>` -- things already proven true (e.g. "semantic-release runs automatically after CI, not before")
+- `<do_not_explore>` -- explicit list of dead ends and already-tried approaches
+
+**How the knowledge graph enables this:**
+- `relevant_files`: KG query "what files are related to the goal?" returns the structural subgraph
+- `prior_sessions`: session store query "what sessions touched these files in the last 7 days?"
+- `established_patterns`: AGENTS.md + KG pattern nodes
+- `known_facts` and `do_not_explore`: built by the coordinator from prior session outputs
+
+**Without the KG (today):** the coordinator manually includes key context in the prompt. Better than nothing, but requires the coordinator to know what's relevant.
+**With the KG (future):** `worktrain spawn --workflow X --goal "..."` automatically queries the KG and assembles the context bundle. Coordinator just provides the goal.
+
+---
+
+### Decouple goal from trigger definition -- late-bound goals for daemon sessions (Apr 18, 2026)
+
+**The problem:** `goal` is currently required at trigger-definition time (in triggers.yml). For triggers like `mr-review`, the goal is inherently dynamic -- it's the PR title and description, known only when the webhook fires, not when the trigger is configured.
+
+The current workaround: `goalTemplate: "{{$.goal}}"` with the caller passing `{"goal": "Review PR #123..."}` in the webhook payload. This works but is awkward -- the caller must know the payload field convention, and it's not obvious from the trigger definition.
+
+**The right model:** separate "which workflow" (trigger definition) from "what to do" (dispatch-time goal).
+
+```yaml
+# Trigger definition -- no goal required
+triggers:
+  - id: mr-review
+    workflowId: mr-review-workflow-agentic
+    workspacePath: ~/git/myproject
+    # No goal here -- goal comes from dispatch context
+```
+
+```bash
+# Dispatch with goal at call time
+curl -X POST http://localhost:3200/webhook/mr-review \
+  -d '{"goal": "Review PR #123: fix authentication bug"}'
+
+# Or via worktrain spawn
+worktrain spawn --trigger mr-review --goal "Review PR #123: fix authentication bug"
+```
+
+**Implementation options:**
+
+1. **goalTemplate with `$.goal` as the default** -- if no `goal` is set in the trigger and no `goalTemplate` is set, default to `goalTemplate: "{{$.goal}}"`. The webhook payload's `goal` field becomes the canonical way to pass a dynamic goal. Zero breaking changes.
+
+2. **Late-bound goal field on WorkflowTrigger** -- `executeStartWorkflow` accepts `goal` as a separate parameter. The trigger provides everything except the goal; the dispatcher (TriggerRouter) resolves the goal from the webhook payload or a default. This makes the separation explicit at the type level.
+
+3. **Prompt injection** -- the workflow's first step can read `context.goal` which is injected from the webhook payload. The trigger has a static placeholder; the real goal comes through as a context variable. This is how it currently half-works but without the clean API.
+
+**Preferred: Option 1 (default goalTemplate)** -- minimal change, backward compatible, works immediately. If `goal` is absent from the trigger and the webhook payload contains `{"goal": "..."}`, use it. Document this as the standard pattern for dynamic-goal triggers.
+
+**Also needed:** the `worktrain spawn` CLI command should accept `--goal` as a first-class flag (already partially implemented) so coordinator scripts can pass goals without knowing the webhook payload format.
+
+**Why this matters for WorkTrain being production-ready:** most real-world triggers (PR review, issue investigation, incident response) have dynamic goals that depend on what just happened. Static goals in triggers.yml only work for scheduled/cron tasks. Late-bound goals make the whole trigger system composable with external events.
+
+---
+
+### Session identity: a unit of work is one session, not many (Apr 18, 2026)
+
+**The problem:** WorkTrain creates a separate WorkRail session for every workflow run. A task that involves discovery + design + implementation + review + re-review appears as 5 unrelated sessions in the console. There's no way to know they belong together without reading the goals. The user sees 50 flat sessions instead of 10 units of work.
+
+**The correct model:** a session is a unit of work, not a workflow run. "Review PR #559" is one session. It might internally run 3 workflow sessions (context gathering, review, re-review) but the user sees one thing with one identity.
+
+**What's needed:**
+
+**1. Parent-child session relationships**
+`session_created` in the session store gets an optional `parentSessionId` field. When a coordinator spawns a child via `worktrain spawn`, the child carries the parent's ID. The session store becomes a tree.
+
+```typescript
+// session_created event
+{
+  kind: 'session_created',
+  sessionId: 'sess_abc123',
+  parentSessionId: 'sess_root456',  // NEW -- absent for root sessions
+  workflowId: 'wr.discovery',
+  goal: '...'
+}
+```
+
+**2. Root session as the identity**
+The root session is what the user sees. It represents the unit of work ("Review PR #559", "Implement GitHub polling adapter"). Child sessions are implementation details -- they may be visible on drill-down but not in the top-level list.
+
+**3. Console session DAG view**
+The console shows root sessions, each expandable to show the tree of child sessions:
+```
+● Review PR #559                    [3 sessions, 22 min]
+  ├── wr.discovery (context)        [completed, 8 min]
+  ├── mr-review-workflow-agentic    [completed, 11 min]  
+  └── coding-task (fix findings)    [running, 3 min...]
+```
+
+**4. Session identity propagated through coordinator**
+`worktrain spawn` accepts `--parent-session <id>` to link child sessions. The coordinator script passes this when spawning each phase of a pipeline. When spawning via the daemon trigger, the trigger's initial session becomes the root.
+
+**Relationship to coordinator sessions spec:**
+The coordinator sessions spec (`spawn_session` + `await_sessions` tools) handles the orchestration. This spec handles the identity and visibility. They're complementary: coordinator scripts drive the work, session identity makes the work visible as a coherent unit.
+
+**Why this matters:**
+- Today: user sees "what are all these sessions?" -- has to read goals to understand grouping
+- With this: user sees "here are my 5 units of work today" -- each one tells a coherent story
+- The console becomes a work log, not a session log
+
+**Build order:**
+1. Add `parentSessionId` to `session_created` event schema (small, additive)
+2. `worktrain spawn --parent-session <id>` flag (wires through TriggerRouter dispatch)
+3. Console aggregates sessions by root and shows tree on expand
+4. Dashboard "work sessions" view replaces flat session list as default
+
+---
+
+### Trigger-derived tool availability and knowledge configuration (Apr 18, 2026, to investigate)
+
+**Observation:** the trigger already declares what external system matters. A `gitlab_poll` trigger means the agent will be working on GitLab content. A `jira_poll` trigger means Jira. WorkTrain should use this declaration to automatically configure what tools and knowledge sources the agent gets -- no manual per-trigger MCP configuration.
+
+**Idea 1: Implicit tool availability from trigger source**
+If `provider: gitlab_poll` → agent automatically gets GitLab MCP tools.
+If `provider: github_poll` → agent gets GitHub tools.
+If `provider: jira_poll` → agent gets Jira tools.
+The trigger source is a declaration of intent -- WorkTrain infers the tool environment from it. No extra config needed for the common case.
+
+**Idea 2: Trigger as knowledge configuration**
+The trigger could declare where the agent gets different kinds of knowledge:
+
+```yaml
+- id: jira-bug-fix
+  provider: jira_poll
+  knowledge:
+    general:   [glean, confluence]         # background org knowledge
+    codebase:  [github, local-kg]           # structural code knowledge  
+    task:      [jira-ticket, related-prs]   # what this specific task is about
+    style:     [team-conventions, agents-md] # how to do the work
+```
+
+The daemon assembles a pre-packaged context bundle from these sources before the agent starts. The agent skips Phase 0 discovery entirely for the declared knowledge domains.
+
+**Why this is interesting:**
+- Closes the loop between "what triggers the work" and "what context the agent needs"
+- The trigger author knows better than anyone what knowledge sources are relevant
+- Eliminates redundant context gathering across sessions for the same trigger type
+- Natural fit with workspace-scoped MCP config and the knowledge graph
+
+**What needs investigating:**
+- Is the trigger → tool mapping always 1:1 (gitlab_poll → gitlab MCP) or does it need explicit override?
+- What are the right "knowledge categories"? (general, codebase, task, style seem like a reasonable starting set)
+- How does this interact with the knowledge graph? (local-kg is already planned as a knowledge source)
+- Can this be inferred automatically or does it always need explicit declaration?
+- How do you handle a trigger that spans multiple systems (e.g. a Jira ticket about a GitHub PR)?
+
+**This is a design-first item** -- the ideas are promising but the right shape isn't obvious. Needs a discovery pass before any implementation.

package/package.json

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

package/workflows/wr.discovery.json

@@ -1,9 +1,10 @@
 {
   "id": "wr.discovery",
   "name": "Discovery Workflow",
-  "version": "3.1.0",
+  "version": "3.2.0",
+  "validatedAgainstSpecVersion": 3,
   "description": "Use this to explore and think through a problem end-to-end. Moves between landscape exploration, problem framing, candidate generation, adversarial challenge, and uncertainty resolution.",
-  "about": "## Discovery Workflow\n\nThis workflow is for structured thinking through an ambiguous problem, opportunity, or decision  -- the kind where you are not sure of the right answer yet and jumping straight to solutions would be premature.\n\n**What it does:**\nThe workflow selects one of three emphasis paths based on your actual need: `landscape_first` for understanding the current state and comparing options, `full_spectrum` for important or ambiguous problems where both landscape grounding and reframing are needed, and `design_first` when the dominant risk is solving the wrong problem. It then moves through landscape research, stakeholder and problem framing, candidate direction generation, adversarial challenge, and an uncertainty-resolution stage that can close with a recommendation, a targeted research follow-up, or a prototype/test plan. A design document is maintained throughout as the human-facing artifact.\n\n**When to use it:**\n- You face a decision, architectural question, or design problem with no obvious right answer\n- You want to explore an opportunity space before committing to a direction\n- You suspect the stated problem might not be the real problem\n- You need a structured recommendation with explicit tradeoffs and alternatives rather than the first plausible answer\n\n**What it produces:**\nA design document covering: the selected path and framing, landscape takeaways, chosen direction and why it won, the strongest alternative and why it lost, confidence band, residual risks, and next actions.\n\n**How to get good results:**\nDescribe the problem, opportunity, or decision you want help thinking through. State what outcome you want (a recommendation, a comparison, a research plan, a prototype direction). The more context you provide upfront about constraints and anti-goals, the sharper the framing will be.",
+  "about": "## Discovery Workflow\n\nThis workflow is for structured thinking through an ambiguous problem, opportunity, or decision -- the kind where you are not sure of the right answer yet and jumping straight to solutions would be premature.\n\n**What it does:**\nBefore starting any research, the workflow challenges the stated goal: it determines whether you handed it a problem or a solution, surfaces hidden assumptions, and defines what success looks like in concrete observable terms. It then selects one of three emphasis paths based on your actual need: `landscape_first` for understanding the current state and comparing options, `full_spectrum` for important or ambiguous problems where both landscape grounding and reframing are needed, and `design_first` when the dominant risk is solving the wrong problem. The workflow moves through landscape research, stakeholder and problem framing, candidate direction generation, adversarial challenge, and an uncertainty-resolution stage that can close with a recommendation, a targeted research follow-up, or a prototype/test plan. A design document is maintained throughout as the human-facing artifact.\n\n**When to use it:**\n- You face a decision, architectural question, or design problem with no obvious right answer\n- You want to explore an opportunity space before committing to a direction\n- You suspect the stated problem might not be the real problem\n- You need a structured recommendation with explicit tradeoffs and alternatives rather than the first plausible answer\n- You want to make sure you are solving the right problem, not just the one you described\n\n**What it produces:**\nA design document covering: the reframed problem (if the original was solution-framed), the selected path and framing, landscape takeaways, chosen direction and why it won, the strongest alternative and why it lost, confidence band, residual risks, and next actions.\n\n**How to get good results:**\nDescribe the problem, opportunity, or decision you want help thinking through -- or describe the solution you are considering, and let the workflow figure out the underlying problem. State what outcome you want (a recommendation, a comparison, a research plan, a prototype direction). The more context you provide upfront about constraints and anti-goals, the sharper the framing will be.",
   "examples": [
     "Decide whether to build a custom notification system or adopt a third-party service",
     "Explore what the right architecture is for moving our monolith to services",
@@ -53,6 +54,40 @@
     }
   ],
   "steps": [
+    {
+      "id": "phase-0-reframe",
+      "title": "Phase 0a: Reframe the Goal Before Jumping to Solutions",
+      "promptBlocks": {
+        "goal": "Challenge the stated goal before we start researching it. Figure out whether I handed you a problem or a solution, surface the assumptions baked into the framing, and define what success actually looks like.",
+        "constraints": [
+          [
+            {
+              "kind": "ref",
+              "refId": "wr.refs.notes_first_durability"
+            }
+          ],
+          "Do not begin landscape research or candidate generation in this step.",
+          "If the goal is stated as a solution, find the problem behind it -- do not just accept the solution as given.",
+          "Challenge assumptions with specificity: name each assumption, state why it might be wrong, and say what evidence would confirm or refute it.",
+          "Define success in terms of outcomes and observable signals, not just delivery of the stated goal."
+        ],
+        "procedure": [
+          "Classify the stated goal as a `solution_statement` (names a specific solution or approach) or a `problem_statement` (describes an outcome, pain, or gap without prescribing the fix). Record this as `goalType`.",
+          "If `goalType = solution_statement`: identify the underlying problem this solution is trying to solve, name at least one materially different way to solve that problem, and state explicitly whether the stated solution is the best match for the problem or just the most familiar one.",
+          "Challenge exactly 3 key assumptions embedded in the stated goal. For each assumption: state the assumption clearly, explain why it might be wrong, and identify what evidence would confirm or refute it. Record these as `challengedAssumptions`.",
+          "Define what success looks like before any candidates are generated. Success criteria must be concrete and observable -- not 'the problem is solved' but 'we can measure X, users do Y, the system behaves Z'. Record these as `successCriteria`.",
+          "Record a one-sentence `reframedProblem` that captures the real underlying problem, stripped of any solution bias from the original goal.",
+          "Set these keys in the next `continue_workflow` call's `context` object: `goalType`, `reframedProblem`, `challengedAssumptions`, `successCriteria`, `goalWasSolutionStatement`."
+        ],
+        "verify": [
+          "Each of the 3 challenged assumptions is specific enough that someone could disagree with the challenge.",
+          "The success criteria would let a skeptic determine whether the work actually succeeded.",
+          "If the goal was a solution-statement, the underlying problem is stated independently of the proposed solution.",
+          "The reframed problem is meaningfully different from the original goal wording, or you have explicitly noted why the original framing was already problem-shaped."
+        ]
+      },
+      "requireConfirmation": false
+    },
     {
       "id": "phase-0-select-path",
       "title": "Phase 0: Understand, Classify, and Recommend a Path",
@@ -71,13 +106,15 @@
         ],
         "procedure": [
           "Capture: `problemStatement`, `desiredOutcome`, `coreConstraints`, `antiGoals`, `primaryUncertainty`, `knownApproaches`, `importantStakeholders`, `rigorMode`, `automationLevel`, `pathRecommendation`, `pathRationale`, `designDocPath`.",
-          "Choose `landscape_first` when my dominant need is understanding the current landscape or comparing options. Choose `full_spectrum` when both landscape grounding and reframing are needed. Choose `design_first` when the dominant risk is solving the wrong problem or shaping the wrong concept.",
+          "If `goalWasSolutionStatement = true`, set `problemStatement` from `reframedProblem` rather than from the stated goal. Record the original stated goal as `statedGoal` in the design doc so the distinction is visible.",
+          "Choose `landscape_first` when my dominant need is understanding the current landscape or comparing options. Choose `full_spectrum` when both landscape grounding and reframing are needed. Choose `design_first` when the dominant risk is solving the wrong problem or shaping the wrong concept. If `goalWasSolutionStatement = true`, bias toward `design_first` unless the stated solution is clearly the correct framing.",
           "Create or update `designDocPath` with sections for Context / Ask, Path Recommendation, Constraints / Anti-goals, Landscape Packet, Problem Frame Packet, Candidate Directions, Challenge Notes, Resolution Notes, Decision Log, and Final Summary.",
           "Set these keys in the next `continue_workflow` call's `context` object: `problemStatement`, `desiredOutcome`, `coreConstraints`, `antiGoals`, `primaryUncertainty`, `knownApproaches`, `importantStakeholders`, `rigorMode`, `automationLevel`, `pathRecommendation`, `pathRationale`, `designDocPath`.",
           "Also set `goal` in the context object: one sentence describing what you are trying to accomplish. This populates the session title in the Workspace console immediately."
         ],
         "verify": [
           "The chosen path is justified against the other two, not just named.",
+          "If `goalWasSolutionStatement = true`, the `problemStatement` reflects the reframed problem, not the stated solution.",
           "The design doc exists and the path recommendation is recorded there."
         ]
       },
@@ -284,10 +321,11 @@
           "Capture users or stakeholders, jobs or outcomes, pains or tensions, constraints that matter in lived use, success criteria, assumptions, and at least 2 reframes or HMW questions.",
           "If `delegationAvailable = true`, decide whether parallel stakeholder lenses would actually sharpen the result. If yes, run them in parallel. If not, keep going yourself. In either case, you must synthesize the result yourself.",
           "Update `designDocPath` using `problemFrameTemplate`.",
+          "Before finishing, name ONE specific concrete condition that would make the current framing wrong -- not a generic caveat, but a specific thing that if discovered to be true would change the path or direction. Record this as `primaryFramingRisk` in the design doc.",
           "Set these keys in the next `continue_workflow` call's `context` object: `problemFrame`, `primaryUsers`, `tensionCount`, `successCriteriaCount`, `framingRiskCount`, `needsChallenge`, `retriageNeeded`."
         ],
         "verify": [
-          "The framing names what could still be wrong.",
+          "The framing names what could still be wrong -- specifically, not generically.",
           "The frame is strong enough to influence candidate generation and later selection."
         ]
       },
@@ -319,10 +357,11 @@
           "Capture users or stakeholders, jobs or outcomes, pains or tensions, constraints that matter in lived use, success criteria, assumptions, and at least 2 reframes or HMW questions.",
           "If `delegationAvailable = true`, decide whether parallel stakeholder lenses would actually sharpen the result. If yes, run them in parallel. If not, keep going yourself. In either case, you must synthesize the result yourself.",
           "Update `designDocPath` using `problemFrameTemplate`.",
+          "Before finishing, name ONE specific concrete condition that would make the current framing wrong -- not a generic caveat, but a specific thing that if discovered to be true would change the path or direction. Record this as `primaryFramingRisk` in the design doc.",
           "Set these keys in the next `continue_workflow` call's `context` object: `problemFrame`, `primaryUsers`, `tensionCount`, `successCriteriaCount`, `framingRiskCount`, `needsChallenge`, `retriageNeeded`."
         ],
         "verify": [
-          "The framing names what could still be wrong.",
+          "The framing names what could still be wrong -- specifically, not generically.",
           "The framing depth is strong enough to justify a design-first path."
         ]
       },
@@ -335,8 +374,20 @@
       "id": "phase-1g-retriage",
       "title": "Phase 1g: Re-Triage After Early Context",
       "runCondition": {
-        "var": "retriageNeeded",
-        "equals": true
+        "or": [
+          {
+            "var": "retriageNeeded",
+            "equals": true
+          },
+          {
+            "var": "pathRecommendation",
+            "equals": "design_first"
+          },
+          {
+            "var": "pathRecommendation",
+            "equals": "full_spectrum"
+          }
+        ]
       },
       "promptBlocks": {
         "goal": "Reassess the path now that you have real landscape and framing context instead of just my initial wording.",

package/dist/mcp/transports/bridge-entry.d.ts

@@ -1,102 +0,0 @@
-import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
-export interface BridgeConfig {
-    readonly reconnectBaseDelayMs: number;
-    readonly reconnectMaxAttempts: number;
-    readonly forwardTimeoutMs: number;
-    readonly maxRespawnAttempts: number;
-    readonly spawnLockStaleMs: number;
-    readonly waitForPrimaryPollMs: number;
-}
-export declare const DEFAULT_BRIDGE_CONFIG: BridgeConfig;
-type HttpBridgeTransport = {
-    readonly send: (msg: JSONRPCMessage) => Promise<void>;
-    readonly close: () => Promise<void>;
-};
-export type ConnectionState = {
-    readonly kind: 'connecting';
-} | {
-    readonly kind: 'connected';
-    readonly transport: HttpBridgeTransport;
-} | {
-    readonly kind: 'reconnecting';
-    readonly attempt: number;
-    readonly maxAttempts: number;
-    readonly respawnBudget: number;
-} | {
-    readonly kind: 'waiting_for_primary';
-} | {
-    readonly kind: 'closed';
-};
-export type ReconnectOutcome = {
-    readonly kind: 'reconnected';
-} | {
-    readonly kind: 'exhausted';
-} | {
-    readonly kind: 'aborted';
-};
-export type SpawnLockResult = {
-    readonly kind: 'acquired';
-} | {
-    readonly kind: 'skipped';
-    readonly reason: string;
-};
-export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
-export type SpawnLike = (command: string, args: ReadonlyArray<string>, opts: {
-    readonly env: NodeJS.ProcessEnv;
-    readonly detached: boolean;
-    readonly stdio: 'ignore';
-}) => {
-    unref: () => void;
-};
-export type WriteFileSyncLike = (path: string, content: string, opts: {
-    flag: 'wx';
-}) => void;
-export type StatSyncLike = (path: string) => {
-    mtimeMs: number;
-};
-export type UnlinkSyncLike = (path: string) => void;
-export type HealthResponse = {
-    readonly port: number;
-    readonly pid: number;
-};
-export declare function detectHealthyPrimary(port: number, opts?: {
-    retries?: number;
-    baseDelayMs?: number;
-    fetch?: FetchLike;
-}): Promise<HealthResponse | null>;
-export declare function spawnLockPath(port: number): string;
-export declare function acquireSpawnLock(port: number, staleMs: number, deps?: {
-    readonly writeFileSync?: WriteFileSyncLike;
-    readonly statSync?: StatSyncLike;
-    readonly unlinkSync?: UnlinkSyncLike;
-}): SpawnLockResult;
-export declare function releaseSpawnLock(port: number, deps?: {
-    readonly unlinkSync?: UnlinkSyncLike;
-}): void;
-export declare function spawnPrimary(port: number, deps: {
-    spawn: SpawnLike;
-    fetch?: FetchLike;
-}): Promise<void>;
-type ReconnectDeps = {
-    readonly detect: (attempt: number) => Promise<boolean>;
-    readonly config: Pick<BridgeConfig, 'reconnectBaseDelayMs' | 'reconnectMaxAttempts'>;
-    readonly signal: AbortSignal;
-};
-export declare function reconnectWithBackoff(deps: ReconnectDeps): Promise<ReconnectOutcome>;
-type OutcomeHandlerDeps = {
-    readonly setConnectionState: (state: ConnectionState) => void;
-    readonly performShutdown: (reason: string) => void;
-    readonly startReconnectLoop: () => void;
-    readonly startWaitLoop: () => void;
-    readonly triggerSpawn: () => Promise<void>;
-    readonly config: Pick<BridgeConfig, 'reconnectMaxAttempts'>;
-};
-export declare function handleReconnectOutcome(outcome: ReconnectOutcome, reconnectingState: Extract<ConnectionState, {
-    kind: 'reconnecting';
-}>, deps: OutcomeHandlerDeps): Promise<void>;
-export declare function startBridgeServer(primaryPort: number, config?: BridgeConfig, deps?: {
-    spawn?: SpawnLike;
-    fetch?: FetchLike;
-    originalPrimaryPid?: number;
-}): Promise<void>;
-export {};