@exaudeus/workrail 3.66.0 → 3.68.0

package/docs/design/discovery-loop-investigation-B.md

@@ -0,0 +1,287 @@
+# Discovery Loop Investigation B: wr.discovery Infinite Re-run on Issue #393
+
+**Date:** 2026-04-21
+**Issue:** GitHub #393 - "test(daemon): add coverage for loadSessionNotes failure paths"
+**Symptom:** Autonomous pipeline repeatedly runs `wr.discovery` sessions on issue #393. Each session runs for ~30 minutes then stops with `outcome: timeout`. The pipeline never progresses to shaping or coding. The issue stays assigned to `worktrain-etienneb`. The queue keeps re-selecting it every poll cycle.
+
+---
+
+## Timeline of What Actually Happened
+
+All timestamps are UTC. Source: `~/.workrail/events/daemon/2026-04-21.jsonl` and `~/.workrail/queue-poll.jsonl`.
+
+### 2026-04-20 19:10 - Loop begins
+
+Issue #393 is assigned to `worktrain-etienneb` and has a `## Acceptance Criteria` checklist section in its body. `inferMaturity()` scores it as `specced`.
+
+Queue poll starts selecting it every ~5 minutes:
+
+```
+19:10:53  task_selected  reason="has acceptance criteria or checklist"
+19:15:48  task_selected  ...
+19:20:48  task_selected  ...
+... (continues hourly or more frequently through 2026-04-21)
+```
+
+Each selection dispatches `dispatchAdaptivePipeline(goal="test(daemon): ...", workspace=".../workrail")`. The goal contains no PR/MR reference and no dep-bump keyword, so `routeTask()` returns `FULL`. The FULL pipeline spawns `wr.discovery`.
+
+### 2026-04-21 01:53 - First wr.discovery sessions start
+
+```
+01:53:42  session_started  wr.discovery  cd2f1c1f
+01:55:30  session_started  wr.discovery  0913d66e
+01:57:11  session_started  wr.discovery  03b13b82
+01:58:53  session_started  wr.discovery  b586dba9
+02:01:01  session_started  wr.discovery  3846e2a5
+02:02:44  session_started  wr.discovery  2976d1db
+```
+
+Multiple sessions are spawned near-simultaneously because the daemon restarted many times between 01:50 and 02:07 (15+ restarts logged). Each restart clears the in-memory `dispatchingIssues` set, so the idempotency guard is reset and the queue re-dispatches on the first poll cycle after each restart.
+
+### 2026-04-21 05:24 onward - Single-session steady-state
+
+From 05:24 onward, one `wr.discovery` session is spawned per hour (matching the queue poll interval). The pattern is:
+
+```
+05:24:20  session_started   wr.discovery  747b8b81
+05:54:20  session_completed wr.discovery  747b8b81  outcome=timeout
+
+06:24:15  session_started   wr.discovery  063f67e3
+06:54:15  session_completed wr.discovery  063f67e3  outcome=timeout
+
+07:24:15  session_started   wr.discovery  c816e662
+07:54:15  session_completed wr.discovery  c816e662  outcome=timeout
+... (continues through 13:24)
+```
+
+Every session runs for exactly 30 minutes, then times out. No shaping, coding, or review sessions are ever spawned. The issue remains open and assigned to `worktrain-etienneb` throughout.
+
+---
+
+## What Should Have Happened
+
+1. Queue selects issue #393 (maturity=`specced`). **[Correct]**
+2. `dispatchAdaptivePipeline` routes to FULL mode. **[Correct]**
+3. FULL pipeline spawns `wr.discovery` with `DISCOVERY_TIMEOUT_MS = 55 minutes`. **[Correct - coordinator side]**
+4. `wr.discovery` completes successfully within 55 minutes.
+5. FULL pipeline reads the handoff artifact, spawns `wr.shaping`, then `wr.coding-task`.
+6. Coding session opens a PR. PR review runs. PR merges.
+7. Post-merge: issue #393 is closed (either automatically by GitHub when the PR closes it, or explicitly).
+8. On the next queue poll, `pollGitHubQueueIssues()` fetches only open issues - #393 would no longer appear, ending the loop.
+
+Instead:
+- `wr.discovery` sessions time out at 30 minutes (not 55).
+- The FULL pipeline escalates.
+- No downstream phases run.
+- The GitHub issue stays open and assigned.
+- The queue re-selects the issue on every poll cycle indefinitely.
+
+---
+
+## Root Causes
+
+### Root Cause 1 (Primary): Session timeout mismatch - 30 min vs. 55 min
+
+**File:** `src/daemon/workflow-runner.ts:83` and `src/trigger/trigger-listener.ts:436-498`
+
+`DEFAULT_SESSION_TIMEOUT_MINUTES = 30` is the default applied to all sessions that do not receive an explicit `agentConfig.maxSessionMinutes` override.
+
+When the coordinator calls `deps.spawnSession('wr.discovery', ...)`, the implementation in `trigger-listener.ts:492-498` calls `routerRef.dispatch({ workflowId, goal, workspacePath, context, _preAllocatedStartResponse })`. Note that **no `agentConfig` field is passed**. This means the spawned `wr.discovery` session runs under `DEFAULT_SESSION_TIMEOUT_MINUTES = 30`.
+
+The coordinator then calls `deps.awaitSessions([discoveryHandle], DISCOVERY_TIMEOUT_MS)` where `DISCOVERY_TIMEOUT_MS = 55 * 60 * 1000` (55 minutes). But the session itself has already timed out at 30 minutes and returned `outcome: timeout` to the `awaitSessions` poller.
+
+The mismatch:
+
+| Layer | Timeout value | Where set |
+|---|---|---|
+| Session wall-clock (actual) | 30 min | `workflow-runner.ts:83` `DEFAULT_SESSION_TIMEOUT_MINUTES` |
+| Coordinator await (expected) | 55 min | `adaptive-pipeline.ts:39` `DISCOVERY_TIMEOUT_MS` |
+
+The coordinator's 55-minute budget is never consumed because the session dies first at 30 minutes. `awaitSessions` sees `outcome: timeout`, the FULL pipeline returns `{ kind: 'escalated', escalationReason: { phase: 'discovery', reason: 'discovery session timeout' } }`, and nothing more is done.
+
+**Why the sessions time out:** The `wr.discovery` workflow has 22 steps. It needs to do landscape analysis, candidate generation, direction selection, and handoff preparation. 30 minutes is insufficient for this on a complex task, especially when the session is also attempting delegation via `spawn_agent` (which eats into the parent's wall-clock budget).
+
+### Root Cause 2 (Primary): No post-escalation issue lifecycle management
+
+**File:** `src/trigger/polling-scheduler.ts:616-624`
+
+When `dispatchAdaptivePipeline` resolves (with any outcome including `escalated`), the only action taken is:
+
+```typescript
+void dispatchP
+  .then(() => {
+    this.dispatchingIssues.delete(top.issue.number);  // only action
+    console.log(`[QueuePoll] in-flight-clear #${top.issue.number} reason=completed`);
+  })
+  .catch(() => {
+    this.dispatchingIssues.delete(top.issue.number);  // only action
+    console.log(`[QueuePoll] in-flight-clear #${top.issue.number} reason=error`);
+  });
+```
+
+The `PipelineOutcome` returned by the coordinator is **silently discarded**. There is no code that:
+
+- Inspects `outcome.kind` (could be `merged`, `escalated`, or `dry_run`)
+- Adds a `worktrain:failed` or `worktrain:in-progress` label to the GitHub issue on escalation
+- Posts a comment explaining the failure
+- Closes the issue if merged
+- Persists the session ID to the `daemon-sessions/` directory (the sidecar idempotency store)
+
+Without any of these, the queue's only guard against re-selecting a completed/escalated issue is:
+1. **`worktrain:in-progress` label check** (H3 in `doPollGitHubQueue`) - never added
+2. **`/sess_[a-z0-9]+/` in issue body** (H3) - never added
+3. **`dispatchingIssues` in-memory set** - cleared on `dispatchAdaptivePipeline` completion and lost on every daemon restart
+4. **`checkIdempotency()` sidecar scan** - scans `~/.workrail/daemon-sessions/`, but that directory is always empty (the coordinator never writes session files there)
+5. **GitHub issue state = closed** - never triggered because the pipeline never reaches merge
+
+All five guards fail. The issue is re-selected on every subsequent poll cycle.
+
+### Root Cause 3 (Contributing): In-memory `dispatchingIssues` lost on daemon restart
+
+**File:** `src/trigger/polling-scheduler.ts:113`, `private readonly dispatchingIssues = new Set<number>()`
+
+The `dispatchingIssues` set is in-memory only. Each daemon restart clears it completely. The daemon restarted 15+ times between 01:50-02:07 and multiple times thereafter. Every restart causes the set to be re-initialized empty, so the first poll cycle after each restart re-dispatches #393 even if the previous pipeline is still in flight.
+
+The queue poll log shows this clearly:
+
+```
+01:10:39  task_skipped   reason=active_session_in_process  (set is live)
+01:12:29  task_selected  reason=...                         (daemon restarted, set cleared)
+01:12:39  task_skipped   reason=active_session_in_process  (set re-populated)
+01:16:06  task_selected  reason=...                         (daemon restarted again)
+```
+
+The sidecar idempotency check (`checkIdempotency()` scanning `~/.workrail/daemon-sessions/`) was designed to handle cross-restart dedup, but it only works if the coordinator writes JSON files to that directory. It never does.
+
+### Root Cause 4 (Contributing): `daemon-sessions/` directory never populated by coordinator
+
+**File:** `src/trigger/adapters/github-queue-poller.ts:86`, `src/trigger/trigger-listener.ts:436-498`
+
+`checkIdempotency()` scans `~/.workrail/daemon-sessions/` for JSON files containing `context.taskCandidate.issueNumber`. The directory is empty at time of investigation. The coordinator's `spawnSession()` implementation does not write any file to `daemon-sessions/`. The comment in `checkIdempotency()` says:
+
+> "real session files written by persistTokens() contain only { continueToken, checkpointToken, ts } -- no context field. A file without taskCandidate cannot claim ownership of any issue."
+
+So even if a file were written, it would be read as `clear` (not `active`) because it would have no `context.taskCandidate.issueNumber`. The sidecar idempotency check is effectively dead for coordinator-spawned sessions.
+
+---
+
+## Evidence Summary
+
+| Evidence | Source |
+|---|---|
+| 13 wr.discovery sessions completed with `outcome=timeout`, all at exactly ~30 min | `events/daemon/2026-04-21.jsonl` |
+| `DEFAULT_SESSION_TIMEOUT_MINUTES = 30` | `src/daemon/workflow-runner.ts:83` |
+| `DISCOVERY_TIMEOUT_MS = 55 * 60 * 1000` | `src/coordinators/adaptive-pipeline.ts:39` |
+| `spawnSession()` passes no `agentConfig` to `routerRef.dispatch()` | `src/trigger/trigger-listener.ts:492-498` |
+| 73 `task_selected` events for #393 across 19+ hours | `~/.workrail/queue-poll.jsonl` |
+| 0 shaping or coding sessions spawned | `events/daemon/2026-04-21.jsonl` (no `session_started` for `wr.shaping` or `wr.coding-task` linked to #393) |
+| `dispatchAdaptivePipeline` result never inspected | `src/trigger/polling-scheduler.ts:616-624` |
+| `daemon-sessions/` directory is empty | `ls ~/.workrail/daemon-sessions/` |
+| GitHub issue #393 remains `OPEN`, assigned to `worktrain-etienneb` | `gh issue view 393` |
+| 15+ daemon restarts between 01:50-02:07 | `events/daemon/2026-04-21.jsonl` (daemon_started/stopped events) |
+
+---
+
+## Recommended Fixes
+
+### Fix 1 (Critical): Pass `agentConfig.maxSessionMinutes` in coordinator's `spawnSession()`
+
+**File:** `src/trigger/trigger-listener.ts` (the `spawnSession` implementation, lines 492-498) or `src/coordinators/modes/full-pipeline.ts` (the call site).
+
+The `spawnSession` signature already accepts a `context` parameter. The fix is to thread `agentConfig` through the spawn call so the child session gets the correct timeout budget.
+
+**Option A:** Extend `CoordinatorDeps.spawnSession` to accept an optional `agentConfig` parameter:
+
+```typescript
+// In pr-review.ts (CoordinatorDeps interface):
+readonly spawnSession: (
+  workflowId: string,
+  goal: string,
+  workspace: string,
+  context?: Readonly<Record<string, unknown>>,
+  agentConfig?: { readonly maxSessionMinutes?: number; readonly maxTurns?: number },
+) => Promise<Result<string | null, string>>;
+```
+
+Then in `full-pipeline.ts`, pass the coordinator's per-phase timeout:
+
+```typescript
+const discoverySpawnResult = await deps.spawnSession(
+  'wr.discovery',
+  opts.goal,
+  opts.workspace,
+  undefined,
+  { maxSessionMinutes: Math.ceil(DISCOVERY_TIMEOUT_MS / 60_000) },  // 55
+);
+```
+
+And in `trigger-listener.ts`, forward the agentConfig to the dispatch call:
+
+```typescript
+routerRef.dispatch({
+  workflowId,
+  goal,
+  workspacePath: workspace,
+  context,
+  agentConfig,  // forward the injected agentConfig
+  _preAllocatedStartResponse: startResult.value.response,
+});
+```
+
+**Option B (simpler, no signature change):** Set a higher default in `~/.workrail/config.json` or in the trigger definition's `agentConfig.maxSessionMinutes`. This avoids code changes but requires operator action and is less principled (the coordinator already has the right value; it should communicate it).
+
+**Recommendation:** Option A. The coordinator knows the correct budget for each phase. Passing it explicitly is a tighter invariant than relying on a global default. The mismatch between `DEFAULT_SESSION_TIMEOUT_MINUTES=30` and `DISCOVERY_TIMEOUT_MS=55` is a latent bug that would also affect shaping (35 min > 30 min) and coding (65 min > 30 min) sessions.
+
+### Fix 2 (Critical): Handle PipelineOutcome in the queue poller
+
+**File:** `src/trigger/polling-scheduler.ts:616-624`
+
+The `dispatchP.then/catch` blocks must inspect the outcome and take action when the pipeline escalates:
+
+```typescript
+void dispatchP
+  .then((outcome) => {
+    this.dispatchingIssues.delete(top.issue.number);
+    if (outcome.kind === 'escalated') {
+      // Add worktrain:failed label + comment to prevent re-selection
+      void this.markIssueEscalated(top.issue, outcome.escalationReason, source);
+    } else if (outcome.kind === 'merged') {
+      // Issue should be closed by the PR, but add a log entry
+      console.log(`[QueuePoll] pipeline merged for #${top.issue.number}`);
+    }
+  })
+  .catch((err) => {
+    this.dispatchingIssues.delete(top.issue.number);
+    void this.markIssueEscalated(top.issue, { phase: 'dispatch', reason: String(err) }, source);
+  });
+```
+
+`markIssueEscalated()` should:
+1. Add the `worktrain:failed` label to the issue (which is already checked by H3 as `active_session_or_in_progress` - or add a dedicated `worktrain:failed` label to `queueConfig.excludeLabels`)
+2. Post a comment with the escalation reason for operator visibility
+
+Alternatively, a simpler guard: add `worktrain:failed` to `queueConfig.excludeLabels` and have the poller add that label on escalation.
+
+### Fix 3 (Important): Persist issue ownership to `daemon-sessions/` for cross-restart idempotency
+
+**File:** `src/trigger/polling-scheduler.ts` (in `doPollGitHubQueue`) or `src/trigger/trigger-listener.ts` (in `spawnSession`).
+
+Before calling `dispatchAdaptivePipeline`, write a sidecar file to `~/.workrail/daemon-sessions/<issueNumber>.json` with content `{ "context": { "taskCandidate": { "issueNumber": N } } }`. Remove this file in the `.then`/`.catch` completion handler.
+
+This makes `checkIdempotency()` effective across daemon restarts. The existing logic in `github-queue-poller.ts:305-356` already handles this correctly - it just needs a file to read.
+
+### Fix 4 (Secondary): Add a 30-second dedup TTL extension when the daemon restarts
+
+**File:** `src/trigger/polling-scheduler.ts` (start of `doPollGitHubQueue`)
+
+The 30-second dedup window in `TriggerRouter._recentAdaptiveDispatches` is lost on restart. A short startup delay (e.g., wait 60 seconds before the first post-restart poll cycle) would reduce the burst of duplicate dispatches during rapid restart sequences. This is a band-aid; Fix 3 is the correct structural solution.
+
+---
+
+## Non-Causes (Ruled Out)
+
+- **Queue filter not working:** The queue correctly filters to only open issues assigned to `worktrain-etienneb`. Issue #393 legitimately matches because it is open and assigned.
+- **`inferMaturity()` incorrect:** #393 has `## Acceptance Criteria` with `- [ ]` checklist items. `specced` is the correct maturity.
+- **`routeTask()` routing to wrong mode:** The goal "test(daemon): add coverage..." correctly routes to FULL (no PR reference, no dep-bump keywords, no pitch file).
+- **`wr.discovery` workflow definition incorrect:** The workflow has 22 steps and is substantive. The issue is runtime timeout, not workflow structure.
+- **Coordinator logic incorrect:** The FULL pipeline's escalation on discovery timeout is correct behavior. The bug is that escalation has no consequence on the queue side.

package/docs/design/exploration-workflow-candidates.md

@@ -0,0 +1,205 @@
+# Design Candidates: exploration-workflow.json Gap
+
+*Human-facing artifact only. Durable truth is in workflow step notes and context variables.*
+
+*This document is raw investigative material for the main agent's synthesis — not a final decision.*
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+**T1: Naming backward-compatibility vs. canonical taxonomy**
+`start_workflow exploration-workflow` throws `WorkflowNotFoundError` (-32001, hard error). The storage layer (`file-workflow-storage.ts:254`) does exact-ID lookup via `sanitizeId()` — no fuzzy match, no redirect. `spec/workflow.schema.json` has `additionalProperties: false` and no `aliases` field — aliases cannot be added to workflow files without a schema change. The only in-bundle fix that requires no schema/engine change is adding a workflow file with `id: "exploration-workflow"`.
+
+**T2: Planning doc currency vs. housekeeping cost**
+Three planning docs (`docs/roadmap/now-next-later.md`, `docs/roadmap/open-work-inventory.md`, `docs/tickets/next-up.md`) list `exploration-workflow.json` as the #1 modernization priority — a workflow that was intentionally deleted 7 months ago. The docs were never updated because the consolidation (commit `a0ddaaac`) was not followed by a completion-update pass.
+
+**T3: YAGNI vs. discoverability pain**
+YAGNI says don't build a general alias mechanism for one case. But the naming gap causes a hard error that the trigger system (`trigger-listener.ts:293`) explicitly treats as serious — it validates workflow IDs at startup to prevent silent `workflow_not_found` failures. These pull in opposite directions.
+
+### Likely Seam
+
+Three simultaneous seams: (1) workflow bundle — `exploration-workflow.json` is gone, `wr.discovery.json` doesn't resolve to the old ID; (2) planning docs — three files with stale references; (3) schema — no alias support exists. The minimum-surface fix uses only seam (1). The architectural fix uses seam (3) and requires a storage layer change.
+
+### What Makes This Hard
+
+The naive fix (update planning docs) doesn't fix the hard error. The clean fix (engine aliases) requires touching the schema and storage layer. The middle path (stub file) is a patch that introduces a non-workflow workflow file into the bundle. A junior developer would update the docs and miss the live error path.
+
+---
+
+## Philosophy Constraints
+
+| Principle | Tension with this problem |
+|---|---|
+| **Structure earns its place** | A fix that prevents a real recurring failure mode earns its keep. A redirect stub and an alias mechanism both qualify. |
+| **YAGNI with discipline** | Don't build a general alias mechanism for one confirmed rename. Stub is the YAGNI-compatible fix; engine alias is premature generalization. |
+| **Architectural fixes over patches** | Alias mechanism is the architecturally correct fix. Stub is an explicit patch. This principle and YAGNI are in direct conflict here. |
+| **Errors are data** | `WorkflowNotFoundError` is a hard -32001 error. Leaving it live is accepting a known broken path. |
+| **Validate at boundaries, trust inside** | The trigger system validates workflow IDs at startup for this reason. The `start_workflow` call is a boundary — errors there should be informative, not hard failures with no guidance. |
+
+**Resolution:** YAGNI wins over "architectural fixes over patches" when one case is confirmed and the general case is speculative. Stub (Candidate B) is the right call for current evidence. Architectural fix (Candidate C) is right when a second rename is confirmed.
+
+---
+
+## Impact Surface
+
+**What must stay consistent if the boundary changes:**
+
+- `bundled-workflow-smoke.test.ts` auto-walks all files in `workflows/` — a stub will be picked up and smoke-tested. It must pass schema validation and produce a valid first-step response.
+- `validate:registry` script checks all bundled workflows. The stub must have a valid `id`, `name`, `version`, and `steps[1+]`.
+- `list_workflows` MCP tool will surface the stub alongside real workflows. The stub name must clearly signal deprecation to avoid confusion.
+- `docs/roadmap/open-work-inventory.md` references `exploration-workflow.json` in the modernization list — must be updated consistently with `now-next-later.md` and `tickets/next-up.md` to avoid contradictory state.
+- Any daemon session that reads the roadmap before starting work will no longer be misled into trying to modernize a deleted file.
+
+---
+
+## Candidates
+
+### Candidate A: Update planning docs only
+
+**Summary:** Update 3 stale planning docs; open 2 new GitHub issues (naming gap, codebase archaeology). No workflow files or source changes.
+
+**Tensions resolved / accepted:**
+- Resolves: T2 (planning docs)
+- Accepts: T1 (hard `WorkflowNotFoundError` stays live), T3 (discoverability pain deferred)
+
+**Boundary:** `docs/roadmap/` and `docs/tickets/` only.
+
+**Why that boundary:** Minimal. Matches the completion-update pattern from AGENTS.md.
+
+**Failure mode:** New issues never prioritized. Hard error persists indefinitely. Agents that read trigger system pattern (`trigger-listener.ts:293`) hit `WorkflowNotFoundError` with no guidance.
+
+**Repo pattern:** Directly follows AGENTS.md completion-update pattern.
+
+**Gains / losses:** Gain: zero blast radius, fast. Loss: hard `WorkflowNotFoundError` stays live; no fix for the error path.
+
+**Scope judgment: Too narrow.** Team's own philosophy treats `workflow_not_found` as a serious failure mode (trigger system, error-handler.ts). Leaving it live while calling the work "done" contradicts that.
+
+**Philosophy fit:** Honors YAGNI. Conflicts with "structure earns its place" and "errors are data."
+
+---
+
+### Candidate B: Thin redirect stub + planning doc updates + new codebase-archaeology issue
+
+**Summary:** Create `workflows/exploration-workflow.json` as a single-step redirect stub. Update 3 planning docs. Open one GitHub issue for codebase-archaeology scope.
+
+**Stub specification:**
+```json
+{
+  "id": "exploration-workflow",
+  "name": "Exploration Workflow [deprecated — use wr.discovery]",
+  "version": "3.0.0",
+  "description": "This workflow ID has moved to wr.discovery. Start a new session with start_workflow wr.discovery instead.",
+  "steps": [{
+    "id": "redirect",
+    "prompt": "This workflow has been renamed. Please start a new session using start_workflow with id 'wr.discovery'. That workflow is the canonical successor to the exploration and design-thinking workflows and covers all the same use cases."
+  }]
+}
+```
+
+Uses only schema-declared fields (`id`, `name`, `version`, `description`, `steps`). No new fields. `additionalProperties: false` is satisfied. Single step satisfies `steps: { minItems: 1 }`.
+
+**Tensions resolved / accepted:**
+- Resolves: T1 (hard error fixed — `exploration-workflow` resolves to stub, step tells user to use `wr.discovery`)
+- Resolves: T2 (planning docs updated)
+- Accepts: T3 partially (codebase-archaeology deferred, but explicitly tracked as new issue)
+
+**Boundary:** Workflow file layer — the minimum-surface boundary. Storage layer does file-based dispatch; adding a file is the natural extension point for this layer.
+
+**Why that boundary is best fit:** Zero engine, zero schema, zero source changes. The problem lives at the workflow-ID resolution boundary; the fix lives at the same boundary.
+
+**Failure mode:** Stub appears in `list_workflows` output alongside real workflows. Users may be confused about two discovery-related entries. The stub's name and description must be explicit enough to avoid this. If `bundled-workflow-smoke.test.ts` runs the stub and checks for substantive output, it may fail quality gates.
+
+**Repo pattern:** Adapts existing pattern (thin-purpose workflow files like `test-session-persistence.json` already exist in the bundle). Redirect-only is a new usage but not architecturally alien.
+
+**Gains / losses:** Gain: hard `WorkflowNotFoundError` fixed immediately; zero source changes; stub is reversible in one commit when engine aliases ship. Loss: non-workflow file in the workflow bundle; potential `list_workflows` confusion; stub accumulates debt if not eventually replaced.
+
+**Scope judgment: Best-fit.** Fixes the real failure mode (hard error) at the minimum surface. Remaining open question explicitly scoped.
+
+**Philosophy fit:** Honors "structure earns its place" (prevents real recurring failure), YAGNI (minimal stub only), "validate at boundaries" (error caught at `start_workflow` boundary). Explicit conflict: "architectural fixes over patches" — the stub is a patch. Accepted tradeoff.
+
+---
+
+### Candidate C: Engine alias feature
+
+**Summary:** Add `aliases?: readonly string[]` to `spec/workflow.schema.json`; extend `getWorkflowById` in `src/infrastructure/storage/file-workflow-storage.ts` to build an alias-to-canonical-id map during index construction and try secondary alias lookup on not-found; populate `wr.discovery.json` with `aliases: ["exploration-workflow", "design-thinking-workflow"]`. Update 3 planning docs.
+
+**Feature specification:**
+- Schema change: `"aliases": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }` added to `spec/workflow.schema.json` as an optional property.
+- Storage change: In `getWorkflowIndex()` (`file-workflow-storage.ts`), two-pass index build: first pass builds primary-id index, second pass adds `aliasId → canonicalId` mappings. In `getWorkflowById`, when `index.get(safeId)` returns null, try `aliasIndex.get(safeId)` to get the canonical ID, then retry.
+- Alias uniqueness enforcement: Schema validator rejects workflows where an alias collides with any other workflow's primary ID or alias.
+- Workflow file change: `wr.discovery.json` declares `"aliases": ["exploration-workflow", "design-thinking-workflow"]`.
+- No `src/v2/durable-core/` changes required — alias resolution happens at the storage/registry layer.
+
+**Tensions resolved / accepted:**
+- Resolves: T1 (naming hard error fixed architecturally)
+- Resolves: T3 (YAGNI pressure partially — alias mechanism is general, handles future renames)
+- Resolves: T2 (planning docs updated)
+- Accepts: T3 partially — codebase-archaeology still a separate open question
+
+**Boundary:** Schema + storage layer. Additive change to both. No protected `src/v2/durable-core/` code touched.
+
+**Why that boundary:** Architecturally correct. The alias mechanism belongs at the workflow registry/storage layer, not as a workflow file. This is where ID resolution happens.
+
+**Failure mode:** Alias cycles (workflow A aliases to workflow B which aliases back to A) cause infinite loops or index build errors. Duplicate aliases across workflows create ambiguous resolution. Secondary-lookup latency adds to every not-found call. All addressable with defensive implementation — but requires more engineering discipline.
+
+**Repo pattern:** Departs from existing patterns. No alias mechanism exists today. New tests needed. Schema validator must be extended.
+
+**Gains / losses:** Gain: architecturally correct; no stub debt; `wr.discovery` self-documents its predecessors; generalizes to future renames. Loss: substantially larger scope; schema + storage + tests; requires new validator logic; slower to ship.
+
+**Scope judgment: Too broad** for current evidence. One confirmed rename. No second rename in the backlog. YAGNI says don't build for a case that isn't confirmed.
+
+**Philosophy fit:** Honors "architectural fixes over patches." Honors "structure earns its place." Conflicts with YAGNI — general feature for one case.
+
+---
+
+## Comparison and Recommendation
+
+### Tensions vs. candidates matrix
+
+| Tension | A | B | C |
+|---|---|---|---|
+| T1: Naming hard error | ✗ | ✓ | ✓ |
+| T2: Planning doc currency | ✓ | ✓ | ✓ |
+| T3: YAGNI vs. discoverability | ✓ | ~ | ✗ |
+
+### Decision criteria verdict
+
+| Criterion | A | B | C |
+|---|---|---|---|
+| Resolve roadmap item without losing intent | ✓ | ✓ | ✓ |
+| Address naming/discoverability gap | ✗ | ✓ | ✓ |
+| Scope new work distinctly | ~ | ✓ | ~ |
+| Actionable without unavailable session analytics | ✓ | ✓ | ✓ |
+
+### Recommendation: **Candidate B**
+
+B is the only candidate that satisfies all 4 decision criteria. A is strictly dominated by B (same doc fix, doesn't fix hard error). C is premature generalization for one confirmed case.
+
+**Core rationale:** One deleted workflow causing one hard error. Fix: one file. The storage layer's file-based dispatch makes "add a file" the natural, minimum extension point. Zero engine changes. The stub is reversible in one commit when Candidate C is eventually justified.
+
+---
+
+## Self-Critique
+
+**Strongest argument against Candidate B:** The stub is explicit technical debt. `list_workflows` will return two discovery-related entries and users may be confused. The stub's step prompt tells users to restart their session entirely — a friction point. "Architectural fixes over patches" is a stated first-class principle, and a stub is an explicit patch.
+
+**Why Candidate A lost:** Strictly dominated by B. Same planning doc fix, doesn't fix the hard error. The additional work for B is one stub file. No scenario where A is better than B.
+
+**What would justify Candidate C:** (1) A second workflow consolidation creates another `WorkflowNotFoundError`; OR (2) the project owner explicitly decides alias support is a product feature worth shipping; OR (3) the stub causes confirmed user confusion in `list_workflows` and a `hidden`/`deprecated` schema field would be needed anyway (at which point the schema is already being changed, so adding `aliases` is marginal cost).
+
+**Assumption that invalidates Candidate B:** If `bundled-workflow-smoke.test.ts` enforces that all workflow files must produce substantive exploration outputs (not redirect-only prompts), the stub fails quality gates. The smoke test auto-walks all files in `workflows/`. If it checks output quality, not just schema validity, the stub fails. Risk assessment: low — the smoke test is a structural validation test, not an output-quality test — but verify before shipping.
+
+---
+
+## Open Questions for the Main Agent
+
+1. **Smoke test compatibility:** Does `tests/lifecycle/bundled-workflow-smoke.test.ts` check only schema validity and step reachability, or does it also assert on output quality? The stub passes the former; may fail the latter.
+
+2. **list_workflows filtering:** Is there any existing mechanism to mark a workflow as deprecated or hidden from `list_workflows` output? If not, is the stub's explicit `[deprecated]` naming suffix sufficient?
+
+3. **Project owner intent:** The consolidation commit (`a0ddaaac`) was AI-authored (Firebender co-author). The metaGuidance "canonical successor" claim was written by the same session. Does the project owner independently confirm that wr.discovery fully covers the exploration use case, or should a human review be requested before closing this item?
+
+4. **Codebase-archaeology gap:** Is there evidence in session history that users invoke wr.discovery for "explore this codebase" tasks and find it mis-shaped? This would change the recommendation from "open a new issue" to "create `wr.explore.json` now."

package/docs/design/exploration-workflow-design-review.md

@@ -0,0 +1,166 @@
+# Design Review Findings: exploration-workflow.json Gap
+
+*Human-facing artifact. Durable truth is in step notes and context variables.*
+
+*Optimized for main-agent synthesis — concise and actionable.*
+
+---
+
+## Selected Direction
+
+**Candidate B (hybrid variant):** Thin redirect stub at `workflows/exploration-workflow.json` + update `wr.discovery.json` description to name predecessors + update 3 planning docs + open 1 GitHub issue for codebase-archaeology scope.
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Status | Condition for failure |
+|---|---|---|
+| Stub is a patch not an architectural fix | Acceptable | Escalate to engine alias (Candidate C) on second workflow rename |
+| Stub appears in list_workflows alongside wr.discovery | Acceptable | Monitor for user confusion; fix by name if needed |
+| Codebase-archaeology gap deferred to GitHub issue | Acceptable conditional | Stub prompt MUST explicitly distinguish problem-space exploration from codebase archaeology |
+
+All three tradeoffs are acceptable under current conditions. No invariant is violated.
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Severity | Coverage | Missing Mitigation |
+|---|---|---|---|
+| Stub accumulates indefinitely, alias feature never ships | LOW-MEDIUM | Partially handled | Add technical debt note to stub `description`; GitHub issue should note Candidate C pivot condition |
+| Stub prompt too vague, misleads agents about codebase-archaeology scope | **MEDIUM — HIGHEST RISK** | Handled only if prompt written as specified | None beyond correct prompt authoring |
+| list_workflows confusion between stub and wr.discovery | LOW | Handled by stub name with `[deprecated]` | None required without evidence |
+
+**Most dangerous:** FM2 (vague prompt). Only silent failure mode — agents won't error, they'll silently use wr.discovery for the wrong job. The required stub prompt is the mitigation; it is non-optional.
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Runner-up (Candidate C — engine alias):** One element worth borrowing: update `wr.discovery.json`'s description to name predecessor IDs. Zero schema changes. One sentence. Survives stub deletion. Adopted into the hybrid.
+
+**Simpler variant (no stub file):** Fails decision criterion 2. `WorkflowNotFoundError` fires before any description is visible. The stub is required.
+
+**Hybrid verdict:** Stub + wr.discovery description update is strictly better than stub alone. Adopted.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|---|---|
+| Structure earns its place | ✓ Satisfied — stub prevents real recurring failure |
+| YAGNI with discipline | ✓ Satisfied — no speculative abstractions |
+| Errors are data | ✓ Satisfied — hard error path actively fixed |
+| Observability as a constraint | ✓ Satisfied — three visibility improvements |
+| Document "why" not "what" | ✓ Satisfied — stub prompt and description document rationale |
+| Architectural fixes over patches | ~ Tension — stub is a patch; accepted because YAGNI counterbalances for one case |
+| Make illegal states unrepresentable | ~ Informational — `deprecated: true` field would be cleaner but requires schema change; name-based convention is sufficient |
+
+No principle is violated in a way that creates correctness or reliability risk.
+
+---
+
+## Findings
+
+### ORANGE: Stub spec was missing required `title` field on step
+
+**Discovery:** `standardStep` schema requires `id` AND `title` (not just `id`). The spec in `design-candidates.md` omitted `title` on the step definition. A stub built from that spec would fail schema validation and the smoke test.
+
+**Resolution:** Corrected spec (see Recommended Revisions). Add `"title": "This workflow has moved"` to the step. Verified against schema.
+
+---
+
+### ORANGE: Stub prompt content is non-optional — vague prompt creates silent misleading guidance
+
+**Discovery:** If the stub's step prompt is simplified to "use wr.discovery instead," it encodes a false assumption: that wr.discovery covers codebase archaeology. This is the highest-risk failure mode.
+
+**Resolution:** The stub's step prompt is a hard deliverable requirement. See Recommended Revisions for exact required wording.
+
+---
+
+### YELLOW: Candidate C pivot condition must be explicitly tracked
+
+**Discovery:** The stub creates technical debt that should trigger Candidate C (engine alias feature) when a second workflow rename is confirmed. Without an explicit tracking mechanism, the debt persists invisibly.
+
+**Resolution:** (1) Add a note to stub's `description` field. (2) Include Candidate C pivot condition in the GitHub issue for codebase-archaeology scope.
+
+---
+
+### YELLOW: wr.discovery description update not yet applied
+
+**Discovery:** The hybrid design requires updating `wr.discovery.json`'s description to name predecessor IDs. This was added in the hybrid review but is not yet reflected in any existing doc.
+
+**Resolution:** See Recommended Revisions.
+
+---
+
+## Recommended Revisions
+
+### Revision 1 — Corrected stub specification (REQUIRED)
+
+```json
+{
+  "id": "exploration-workflow",
+  "name": "Exploration Workflow [deprecated — use wr.discovery]",
+  "version": "3.0.0",
+  "description": "This workflow ID has moved. The exploration and design-thinking workflows were consolidated into wr.discovery (Discovery Workflow) in March 2026. Temporary redirect stub — replace with engine-level alias support if a second workflow rename creates another WorkflowNotFoundError.",
+  "steps": [
+    {
+      "id": "redirect",
+      "title": "This workflow has moved",
+      "prompt": "This workflow has been renamed and restructured as 'wr.discovery' (Discovery Workflow).\n\nFor problem-space exploration, decision-making, design thinking, or comparing approaches to an ambiguous problem: start a new session with start_workflow using id 'wr.discovery'.\n\nImportant distinction: if your goal is to systematically map or understand an unfamiliar codebase — tracing architecture, call stacks, data flows, or module structure — that is a different job from problem-space exploration. No dedicated bundled workflow covers it yet. Use your standard code investigation tools (Grep, Read, Bash) directly for that task."
+    }
+  ]
+}
+```
+
+All required fields satisfied: `id` (≥3 chars), `name` (≥1), `description` (≥1), `version`, `steps` (minItems: 1). Step has `id` and `title`. Prompt ≤8192 chars.
+
+---
+
+### Revision 2 — wr.discovery description update (REQUIRED for hybrid)
+
+Current `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."`
+
+Proposed: `"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. This is the canonical successor to exploration-workflow and design-thinking-workflow — if you are looking for either of those by name, this is the right workflow."`
+
+---
+
+### Revision 3 — Planning doc updates (REQUIRED)
+
+Three files need updating:
+
+**`docs/roadmap/now-next-later.md` (Next section):**
+Remove: `exploration-workflow.json is the highest-priority candidate.`
+Replace with: `exploration-workflow.json was superseded by wr.discovery (see open-work-inventory.md). The remaining open question is whether a codebase-archaeology workflow (wr.explore or equivalent) is warranted — tracked as a separate GitHub issue.`
+
+**`docs/roadmap/open-work-inventory.md` (Legacy workflow modernization section):**
+Update status to: complete for exploration-workflow (superseded by wr.discovery v3.2.0, redirect stub added). Open: mr-review-workflow.json, bug-investigation.json remain on the modernization list.
+
+**`docs/tickets/next-up.md` (Ticket 2):**
+Replace "Legacy workflow modernization -- exploration-workflow.json" with a note: superseded. Point to the new GitHub issue for codebase-archaeology scope.
+
+---
+
+### Revision 4 — New GitHub issue (REQUIRED)
+
+Title: `feat(workflows): decide whether codebase-archaeology exploration warrants a new wr.explore workflow`
+
+Body should include:
+- Problem: wr.discovery is shaped for problem-space exploration and strategic decision-making. Systematic codebase mapping (architecture understanding, call stack tracing) is a different job with different tools.
+- Evidence gap: no session data confirming this gap is real vs. hypothetical.
+- Acceptance criteria: investigate whether wr.discovery is being used for codebase-archaeology tasks and producing mis-shaped outputs; if confirmed, create wr.explore.json with explicit scope.
+- Pivot condition for Candidate C: if a second workflow rename creates another WorkflowNotFoundError, escalate this issue to include engine alias support (adds `aliases` field to schema and secondary lookup to file-workflow-storage.ts).
+- Labels: `feature`, `next`
+
+---
+
+## Residual Concerns
+
+1. **The consolidation commit was AI-authored (Firebender).** The metaGuidance "canonical successor" claim was written by an AI session, not explicitly confirmed by the project owner. Before closing the roadmap item, it would be good to have the project owner verify that wr.discovery fully covers their intended exploration use case. This is a human-gate, not a technical concern.
+
+2. **Codebase-archaeology use case is unverified.** No session data is available to confirm whether this gap causes real-world pain. The GitHub issue captures it, but without evidence it may never be prioritized. Acceptable — it's explicitly tracked rather than silently ignored.
+
+3. **Stub name contains square brackets.** `[deprecated — use wr.discovery]` in the workflow name is a convention, not a schema-enforced status. If the project later adds a `deprecated: boolean` field to the schema, this convention should be replaced. Low priority.